codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/hig-patterns/references/managing-notifications.md

@@ -0,0 +1,99 @@
+---
+title: "Managing notifications | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/managing-notifications
+
+# Managing notifications
+
+Notifications can give people timely and important information, whether the device is locked or in use.
+
+![A sketch of bell with a small overlapping circle, suggesting a notification sound. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/ba0d1e169421e490842a4009ee7d09e5/patterns-managing-notifications-intro%402x.png)
+
+You need to get permission before sending any notification. The system lets people change this decision in settings, where they can also silence all notifications (except for government alerts in some locales).
+
+## [Integrating with Focus](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Integrating-with-Focus)
+
+People appreciate receiving a notification for something they care about, but they don’t always appreciate being interrupted. To help people manage the experience, the system lets them specify delivery times and set up a 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.
+
+
+
+
+People identify the contacts and apps that can break through a Focus to deliver notification alerts. In a Work Focus, for example, people might want to receive alerts from work colleagues, family members, and work-related apps as soon as notifications arrive. People might also want to receive all Time Sensitive notification alerts during a Focus. A _Time Sensitive_ notification contains essential information people appreciate getting right away.
+
+Important
+
+Even though a Focus might delay the delivery of a notification alert, the notification itself is available as soon as it arrives.
+
+To support these behavior customizations, you first identify the types of notifications your app or game can send. If you support direct communications — like phone calls and messages — you use _communication_ notifications; for all other types of tasks, you use _noncommunication_ notifications. To support communication notifications, you adopt SiriKit intents, which means people can use Siri to customize notification behaviors; for developer guidance, see [`INSendMessageIntent`](https://developer.apple.com/documentation/Intents/INSendMessageIntent) and [`UNNotificationContentProviding`](https://developer.apple.com/documentation/UserNotifications/UNNotificationContentProviding).
+
+You need to specify a system-defined interruption level for each noncommunication notification you send. The system uses the interruption level to help determine when to deliver the alert; when a communication notification arrives, the system uses the sender to determine when to deliver the alert.
+
+The system defines four interruption levels for noncommunication notifications:
+
+  * _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.
+
+
+
+
+Notification alerts in each system-defined interruption level can behave in the following ways:
+
+Interruption level| Overrides scheduled delivery| Breaks through Focus| Overrides Ring/Silent switch on iPhone and iPad  
+---|---|---|---  
+Passive| No| No| No  
+Active| No| No| No  
+Time Sensitive| Yes| Yes| No  
+Critical| Yes| Yes| Yes  
+  
+Note
+
+Because a Critical notification can override the Ring/Silent switch and break through scheduled delivery and Focus, you must get an entitlement to send one.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Best-practices)
+
+**Build trust by accurately representing the urgency of each notification.** People have several ways to adjust how they receive your notifications — including turning off all notifications — so it’s essential to be as realistic as possible when assigning an interruption level. You don’t want people to feel that a notification uses a high level of urgency to interrupt them with low-priority information.
+
+**Use the Time Sensitive interruption level only for notifications that are relevant in the moment.** To help people understand the benefits of letting Time Sensitive notifications break through a Focus or scheduled delivery, make sure the notification is about an event that’s happening now or will happen within an hour. The first time a Time Sensitive notification arrives from your app, the system describes how such a notification works and gives people a way to turn it off if they don’t agree that the information requires their immediate attention. Going forward, the system periodically gives people additional opportunities to evaluate how your Time Sensitive notification is working for them. For developer guidance, see [`UNNotificationInterruptionLevel`](https://developer.apple.com/documentation/UserNotifications/UNNotificationInterruptionLevel).
+
+## [Sending marketing notifications](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Sending-marketing-notifications)
+
+Don’t use notifications to send marketing or promotional content unless people explicitly agree to receive such information. When people want to learn about new features, content, or events related to your app or game, they can grant their permission to receive marketing notifications. For example, people who use a subscription app might appreciate getting an offer to become a subscriber, and game players might want to receive a special offer related to a live game event.
+
+**Never use the Time Sensitive interruption level to send a marketing notification.** People may have agreed to receive marketing notifications from your app, but such a notification must never break through a Focus or scheduled delivery setting.
+
+**Get people’s permission if you want to send them promotional or marketing notifications.** Before you send these notifications to people, you must receive their explicit permission to do so. Create an alert, modal view, or other interface that describes the types of information you want to send and gives people a clear way to opt in or out.
+
+**Make sure people can manage their notification settings within your app.** In addition to requesting permission to send informational or marketing notifications, you must also provide an in-app settings screen that lets people change their choice. For guidance, see [Settings](https://developer.apple.com/design/human-interface-guidelines/settings).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS._
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#watchOS)
+
+By default, the notification settings people use for apps on their iPhone apply to the same apps on their Apple Watch. People can manage these settings in the Apple Watch app on iPhone, or they can access per-notification options — such as Mute 1 Hour or Turn off Time Sensitive — by swiping left when a notification arrives on their Apple Watch.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Related)
+
+[Privacy](https://developer.apple.com/design/human-interface-guidelines/privacy)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Developer-documentation)
+
+[User Notifications](https://developer.apple.com/documentation/UserNotifications)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/managing-notifications#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/B63A08EA-8856-4C77-9E1B-EA1CAD990619/4986_wide_250x141_1x.jpg) Send communication and Time Sensitive notifications ](https://developer.apple.com/videos/play/wwdc2021/10091)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/49/3D8237BC-06E3-4711-8552-7008A5D5BAAD/3764_wide_250x141_1x.jpg) The Push Notifications primer ](https://developer.apple.com/videos/play/wwdc2020/10095)
+

package/templates/.agent/skills/hig-patterns/references/modality.md

@@ -0,0 +1,82 @@
+---
+title: "Modality | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/modality
+
+# Modality
+
+Modality is a design technique that presents content in a separate, dedicated mode that prevents interaction with the parent view and requires an explicit action to dismiss.
+
+![A sketch of an active window above an inactive window, suggesting focus on the frontmost window. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/9efb35fd7fafa01ce3447dc6f13ae2d8/patterns-modality-intro%402x.png)
+
+Presenting content modally can:
+
+  * 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
+
+
+
+
+Depending on the platform, you might use different components to present these types of modal experiences. For example, all platforms can present an _alert_ , which is a modal view that delivers important information related to your app or game. In addition, each platform may define various types of modal views for presenting context-specific options, such as _activity views,_ _sheets_ , and _confirmation dialogs_ or _action sheets_. To help people perform a distinct task, iOS, iPadOS, and macOS apps tend to use sheets or popovers, but iPadOS, macOS, and visionOS apps might also just use a separate window.
+
+To provide a temporary experience, like viewing media, or to help people perform a distinct, multistep task, like editing content, apps can offer a full-screen modal experience. In contrast, apps may also offer nonmodal types of full-screen experiences; for guidance, see [Going full screen](https://developer.apple.com/design/human-interface-guidelines/going-full-screen). visionOS apps can offer a range of immersive experiences; for guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/modality#Best-practices)
+
+**Present content modally only when there’s a clear benefit.** A modal experience takes people out of their current context and requires an action to dismiss, so it’s important to use modality only when it helps people focus or make choices that affect their content or device.
+
+**Aim to keep modal tasks simple, short, and streamlined.** If a modal task is too complicated, people can lose track of the task they suspended when they entered the modal view, especially if the modal view obscures their previous context.
+
+**Take care to avoid creating a modal experience that feels like an app within your app.** In particular, presenting a hierarchy of views within a modal task can make people forget how to retrace their steps. If a modal task must contain subviews, provide a single path through the hierarchy and avoid including buttons that people might mistake for the button that dismisses the modal view.
+
+**Consider using a full-screen modal style for in-depth content or a complex task.** A modal experience that fills a window or the device display minimizes distractions, so it can work well for presenting videos, photos, or camera views, or to support a multistep task like marking up a document or editing a photo. When a visionOS app runs alongside other apps in the Shared Space, a full-screen modal presentation fills a window; if people transition the app to a Full Space, the full-screen modal presentation can become a more immersive experience.
+
+**Always give people an obvious way to dismiss a modal view.** In general, it works well to follow the platform conventions people already know. For example, in iOS, iPadOS, and watchOS apps, people typically expect to find a button in the top toolbar or swipe down; in macOS and tvOS apps, people expect to find a button in the main content view.
+
+**When necessary, help people avoid data loss by getting confirmation before closing a modal view.** Regardless of whether people use a dismiss gesture or a button, if closing the view could result in the loss of user-generated content, be sure to explain the situation and give people ways to resolve it. For example, in iOS, you might present an action sheet that includes a save option.
+
+**Make it easy to identify a modal view’s task.** When people enter a modal view, they switch away from their previous context and might not return to it right away. When you provide a title that names the modal view’s task — or additional text that describes the task or provides guidance — you can help people keep their place in your app.
+
+**Let people dismiss a modal view before presenting another one.** Allowing multiple modal views to be visible at the same time tends to create visual clutter and can make your app seem scattered and disorganized. People need to remember the context they were in before a modal view appears, so presenting multiple views adds to people’s cognitive load, especially when a modal view hides another one by appearing on top of it. Although an alert can appear on top of all other content — including other modal views — you never want to display more than one alert at the same time.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/modality#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/modality#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/modality#Related)
+
+[Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets)
+
+[Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+
+[Popovers](https://developer.apple.com/design/human-interface-guidelines/popovers)
+
+[Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets)
+
+[Activity views](https://developer.apple.com/design/human-interface-guidelines/activity-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/modality#Developer-documentation)
+
+[Presentation modifiers](https://developer.apple.com/documentation/SwiftUI/View-Presentation) — SwiftUI
+
+[`UIModalPresentationStyle`](https://developer.apple.com/documentation/UIKit/UIModalPresentationStyle) — UIKit
+
+[Modal Windows and Panels](https://developer.apple.com/documentation/AppKit/modal-windows-and-panels) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/modality#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/1AAA030E-2ECA-47D8-AE09-6D7B72A840F6/10044_wide_250x141_1x.jpg) Get to know the new design system ](https://developer.apple.com/videos/play/wwdc2025/356)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/modality#Change-log)
+
+Date| Changes  
+---|---  
+December 5, 2023| Enhanced guidance for in-depth modal experiences and clarified guidance on multiple modal views.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/templates/.agent/skills/hig-patterns/references/multitasking.md

@@ -0,0 +1,131 @@
+---
+title: "Multitasking | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/multitasking
+
+# Multitasking
+
+Multitasking lets people switch quickly from one app to another, performing tasks in each.
+
+![A sketch of two side-by-side windows in a split view arrangement, suggesting multitasking. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/94f1391bf700ee7af09ad0f966dd7b36/patterns-multitasking-intro%402x.png)
+
+People expect to use multitasking on their devices, and they may think something is wrong if your app doesn’t allow it. With rare exceptions — such as some games, and Apple Vision Pro apps running in a Full Space — every app needs to work well with multitasking.
+
+In addition to app switching, multitasking can present different experiences on different devices; see [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/multitasking#Platform-considerations).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/multitasking#Best-practices)
+
+A great multitasking experience helps people accomplish tasks in multiple apps by managing content in a variety of simultaneous contexts. Because you don’t know when people will initiate multitasking, your app or game always needs to be prepared to save and restore their context.
+
+**Pause activities that require people’s attention or active participation when they switch away.** If your app is a game or a media-viewing app, for example, make sure people don’t miss anything when they switch to another app. When they switch back, let them continue as if they never left.
+
+**Respond smoothly to audio interruptions.** Occasionally, audio from another app or the system itself may interrupt your app’s audio. For example, an incoming phone call or a music playlist initiated by Siri might interrupt your app’s audio. When situations like these occur, people expect your app to respond in the following ways:
+
+  * 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.
+
+
+
+
+For guidance, see [Playing audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio).
+
+**Finish user-initiated tasks in the background.** When someone starts a task like downloading assets or processing a video file, they expect it to finish even if they switch away from your app. If your app is in the middle of performing a task that doesn’t need additional input, complete it in the background before suspending.
+
+**Use notifications sparingly.** Your app can send notifications when it’s suspended or running in the background. If people start an important or time-sensitive task in your app, and then switch away from it, they might appreciate receiving a notification when the task completes so they can switch back to your app and take the next step. In contrast, people don’t generally need to know the moment a routine or secondary task completes. In this scenario, avoid sending an unnecessary notification; instead, let people check on the task when they return to your app. For guidance, see [Managing notifications](https://developer.apple.com/design/human-interface-guidelines/managing-notifications).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/multitasking#Platform-considerations)
+
+ _Not supported in watchOS._
+
+### [iOS](https://developer.apple.com/design/human-interface-guidelines/multitasking#iOS)
+
+On iPhone, multitasking lets people use FaceTime or watch a video in Picture in Picture while they also use a different app.
+
+![A screenshot of the app switcher on iPhone, showing four open apps.](https://docs-assets.developer.apple.com/published/519ce5b2d1298e573aab62d4ea3427c9/multitasking-app-switcher-iphone%402x.png)
+
+The app switcher displays all currently open apps.
+
+![A screenshot of Mail on iPhone, showing an individual email. On top of the email body content, a small image in the bottom-left corner shows the person currently in a FaceTime call.](https://docs-assets.developer.apple.com/published/f68005bf620706a5d6c6c03d09af37f4/multitasking-pip-iphone%402x.png)
+
+A current FaceTime call can continue while people use another app.
+
+### [iPadOS](https://developer.apple.com/design/human-interface-guidelines/multitasking#iPadOS)
+
+On iPad, people can view and interact with the [windows](https://developer.apple.com/design/human-interface-guidelines/windows) of several different apps at the same time. An individual app can also support multiple open windows, which lets people view and interact with more than one window in the same app at one time.
+
+People can use iPad with either full-screen or windowed apps. When full screen, apps occupy the full screen, and people can switch between individual app windows using the app switcher.
+
+![A screenshot of the iPad app switcher in landscape orientation, showing five open apps. Thumbnail representations of the apps are arranged in a grid.](https://docs-assets.developer.apple.com/published/b1c2946808ad75c7036af18706a55b79/multitasking-ipad-app-switcher%402x.png)
+
+When using windowed apps, app windows are resizable, and people can arrange them to suit their needs with behavior similar to macOS. The system provides window controls for common tiling configurations, entering full screen, minimizing, and closing windows. The system identifies the frontmost window by coloring its window controls and casting a drop shadow on windows behind it. For guidance, see [Windows > iPadOS](https://developer.apple.com/design/human-interface-guidelines/windows#iPadOS).
+
+![A screenshot of two windowed apps on iPad in landscape orientation. The frontmost app window overlaps and casts a shadow on the one behind it, and has colored window controls to indicate that the window is active. Both windows sit atop the Home Screen background, and the Dock appears at the bottom.](https://docs-assets.developer.apple.com/published/433d49d66e117152f7cca9605ebe9628/multitasking-ipad-windows-maps-landmarks%402x.png)
+
+Additionally, videos and FaceTime calls can also play in a Picture in Picture overlay above other content regardless of whether apps are full screen or windowed.
+
+Note
+
+Apps don’t control multitasking configurations or receive any indication of the ones that people choose.
+
+To help your app respond correctly when people open it while windowed, make sure it adapts gracefully to different screen sizes. For guidance, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout) and [Windows](https://developer.apple.com/design/human-interface-guidelines/windows); for developer guidance, see [Multitasking on iPad, Mac, and Apple Vision Pro](https://developer.apple.com/documentation/UIKit/multitasking-on-ipad-mac-and-apple-vision-pro). To learn more about how people use iPad multitasking features, see [Use multitasking on your iPad](https://support.apple.com/en-us/HT207582).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/multitasking#macOS)
+
+On Mac, multitasking is the default experience because people typically run more than one app at a time, switching between windows and tasks as they work. When multiple app windows are open, macOS applies drop shadows that make the windows appear layered on the desktop, and applies other visual effects to help people distinguish different window states; for guidance, see [macOS window states](https://developer.apple.com/design/human-interface-guidelines/windows#macOS-window-states).
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/multitasking#tvOS)
+
+On Apple TV, people can play or browse content while also playing movies or TV shows in Picture in Picture (where supported).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/multitasking#visionOS)
+
+On Apple Vision Pro, people can run multiple apps at the same time in the Shared Space, viewing and switching between windows and volumes throughout the space.
+
+Only one window is active at a time in the Shared Space. When people look from one window to another, the window they’re currently looking at becomes active while the previous window becomes more translucent and appears to recede along the z-axis. Closing an app window in the Shared Space transitions the app to the background without quitting it.
+
+Note
+
+When an app is the Now Playing app, closing its window automatically pauses audio playback; if people want to resume playback, they can do so in Control Center without opening the window.
+
+**Avoid interfering with the system-provided multitasking behavior.** When people look from one window to another, visionOS applies a feathered mask to the window they look away from to clarify its changed state. To avoid interfering with this visual feedback, don’t change the appearance of a window’s edges.
+
+Video with custom controls. 
+
+Content description: A recording showing the Notes app and the Settings app in the Shared Space in visionOS. The viewer first repositions the Notes window to slightly overlap the Settings window before activating Settings and then switching back to Notes. Each time an app becomes active, the system applies feathering to the inactive app's window. 
+
+Play 
+
+**Don’t pause a window’s video playback when people look away from it.** In visionOS, as in macOS, people expect the playback they start in one window to continue while they view or perform a task in another window.
+
+**Be prepared for situations where your audio can duck.** Unless an app is currently the Now Playing app, its audio can duck when people look away from it to another app.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/multitasking#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/multitasking#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+[Windows](https://developer.apple.com/design/human-interface-guidelines/windows)
+
+[Playing video](https://developer.apple.com/design/human-interface-guidelines/playing-video)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/multitasking#Developer-documentation)
+
+[Responding to the launch of your app](https://developer.apple.com/documentation/UIKit/responding-to-the-launch-of-your-app) — UIKit
+
+[Multitasking on iPad, Mac, and Apple Vision Pro](https://developer.apple.com/documentation/UIKit/multitasking-on-ipad-mac-and-apple-vision-pro) — UIKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/multitasking#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/873F40BE-101A-4C0D-99F0-F5C7CE7B47A3/10046_wide_250x141_1x.jpg) Elevate the design of your iPad app ](https://developer.apple.com/videos/play/wwdc2025/208)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/A8CAF870-197F-4982-83D8-56513E5D7D0B/10000_wide_250x141_1x.jpg) Make your UIKit app more flexible ](https://developer.apple.com/videos/play/wwdc2025/282)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/multitasking#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Reorganized guidance in platform considerations, and added guidance for multitasking with multiple windows in iPadOS.  
+December 5, 2023| Added artwork for primary and auxiliary windows in iPadOS.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/templates/.agent/skills/hig-patterns/references/offering-help.md

@@ -0,0 +1,117 @@
+---
+title: "Offering help | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/offering-help
+
+# Offering help
+
+Although the most effective experiences are approachable and intuitive, you can provide contextual help when necessary.
+
+![A sketch of a question mark, suggesting help is available. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/c09494b87143553d5b544aade5282148/patterns-offering-help-intro%402x.png)
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/offering-help#Best-practices)
+
+**Let your app’s tasks inform the types of help people might need.** For example, you might help people perform simple, one- or two-step tasks by displaying an inline view that succinctly describes the task. In contrast, if your app or game supports complex or multistep tasks you might want to provide a tutorial that teaches people how to accomplish larger goals. In general, directly relate the help you provide to the precise action or task people are doing right now and make it easy for people to dismiss or avoid the help if they don’t need it.
+
+**Use relevant and consistent language and images in your help content.** Always make sure guidance is appropriate for the current context. For example, if someone’s using the Siri Remote with your tvOS experience, don’t show tips or images that feature a game controller. Also be sure the terms and descriptions you use are consistent with the platform. For example, don’t write copy that tells people to click a button on an iPhone or tap a menu item on a Mac.
+
+**Make sure all help content is inclusive.** For guidance, see [Inclusion](https://developer.apple.com/design/human-interface-guidelines/inclusion).
+
+**Avoid bloating your help content by explaining how standard components or patterns work.** Instead, describe the specific action or task that a standard element performs in your app or game. If your experience introduces a unique control or expects people to use an input device in a nonstandard way — such as holding the Siri Remote rotated 90 degrees — orient people quickly, preferring animation or graphics to educate instead of a lengthy description.
+
+## [Creating tips](https://developer.apple.com/design/human-interface-guidelines/offering-help#Creating-tips)
+
+A tip is a small, transient view that briefly describes how to use a feature in your app. Tips are a great way to teach people about new or less obvious features in your app, or help them discover faster ways to accomplish a task. For developer guidance, see [TipKit](https://developer.apple.com/documentation/TipKit).
+
+**Use the most appropriate tip type for your app’s user interface.** Display a popover tip when you want to preserve the content flow, or an inline tip when you want to ensure that surrounding information is visible. You can use an annotation-style inline tip when pointing to a specific UI element, or a hint-style tip when it’s not related to a specific piece of UI.
+
+![An illustration of a popover-style tip on iPhone. The tip appears atop nearby content, and points to a feature depicted by a blue star icon. The content beneath the tip is obscured.](https://docs-assets.developer.apple.com/published/2a1deca274cc855ac01321f3a583b858/offering-help-tip-popover%402x.png)
+
+Popover
+
+![An illustration of an annotation-style tip on iPhone. The tip is embedded among the surrounding content, and points to a feature depicted by a blue star icon. Displaced text appears above and below the tip.](https://docs-assets.developer.apple.com/published/e2b5c6a0a9d94a6c7a16cb1b2c9be517/offering-help-tip-annotation%402x.png)
+
+Annotation
+
+![An illustration of an hint-style tip on iPhone. The tip is embedded among the surrounding content. Displaced text appears above and below the tip.](https://docs-assets.developer.apple.com/published/706238176beb6869a8cf4cd06e22912c/offering-help-tip-hint%402x.png)
+
+Hint
+
+**Use tips for simple features.** Tips work best on features that are easy to describe and that people can complete with a few simple steps. If a feature requires more than three actions, it’s probably too complicated for a tip.
+
+**Make tips short, actionable, and engaging.** A tip’s goal is to encourage people to try new features. Use direct, action-oriented language to describe what the feature does and explain how to use it. Keep your tips to one or two sentences and avoid including content that’s promotional or related to a different feature or user flow. Promotional content is anything that advertises, sells, or isn’t aligned with the current context of what the person is doing.
+
+**Define rules to help ensure your tips reach the intended audience.** Not everyone benefits from every tip. For example, people who’ve already used a feature won’t appreciate viewing a tip that describes it. Use parameter-based or event-based eligibility rules to control when a tip appears, and only display a tip if someone might benefit from its use. When your app has more than one tip, set the display frequency so tips display at a reasonable cadence — for example, once every 24 hours.
+
+**If there’s an image or symbol that people associate with the feature, consider including it in the tip, and prefer the filled variant.** For example, a tip with a star can help people understand that the tip is related to favorites.
+
+![An illustration of a hint-style tip with an unfilled blue star symbol on the leading side.](https://docs-assets.developer.apple.com/published/e4a119cd09255a5e22c5132263c39cd9/offering-help-tip-symbol-usage-unfilled-incorrect%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+![An illustration of a hint-style tip with a filled blue star symbol on the leading side.](https://docs-assets.developer.apple.com/published/be5eb0f23474419bcb3b182b24c24d77/offering-help-tip-symbol-usage-filled-correct%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
+
+If the feature is represented by an image that the tip connects to directly, avoid repeating the same image in both the tip and the UI.
+
+![An illustration of an annotation-style tip pointing to a feature depicted by a blue star icon. The tip includes a similar blue star symbol on its leading side.](https://docs-assets.developer.apple.com/published/b35499b146567d76a7ca996cf3efb9e9/offering-help-tip-symbol-usage-incorrect%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+![An illustration of an annotation-style tip pointing to a feature depicted by a blue star icon. The tip is text-only and omits an accompanying symbol.](https://docs-assets.developer.apple.com/published/afa3b233a9ec05e15e54fd1ec909c015/offering-help-tip-symbol-usage-correct%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
+
+**Use buttons to direct people to information or options.** If your feature has settings people can customize, or you want to redirect people to an area where they can learn more about a feature, consider adding a button. Buttons can take people directly to the settings where they make adjustments. Or if there’s more information people might find useful, add a button to take them to additional resources, such as a setup flow.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/offering-help#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, tvOS, or watchOS._
+
+### [macOS, visionOS](https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS)
+
+A _tooltip_ (called a _help tag_ in user documentation) displays a small, transient view that briefly describes how to use a component in the interface. In apps that run on a Mac — including iPhone and iPad apps — tooltips can appear when a person holds the pointer over an element; in visionOS apps, a tooltip can appear when a person looks at an element or holds the pointer over it. For developer guidance, see [`help(_:)`](https://developer.apple.com/documentation/SwiftUI/View/help\(_:\)-6oiyb).
+
+![An illustration of a toolbar in macOS Finder with the pointer over the Back button. A tooltip with the title See folders you viewed previously appears beneath the pointer.](https://docs-assets.developer.apple.com/published/a5dc5c63ac62773df2b4aea95ad85f39/offering-help-macos-tooltip-help-tag%402x.png)
+
+**Describe only the control that people indicate interest in.** When people want to know how to use a specific control, they don’t want to learn how to use nearby controls or how to perform a larger task.
+
+**Explain the action or task the control initiates.** It often works well to begin the description with a verb — for example, “Restore default settings” or “Add or remove a language from the list.”
+
+**In general, avoid repeating a control’s name in its tooltip.** Repeating the name takes up space in the tooltip and rarely adds value to the description.
+
+**Be brief.** As much as possible, limit tooltip content to a maximum of 60 to 75 characters (note that localization often changes the length of text). To make a description brief and direct, consider using a sentence fragment and omitting articles. If you need a lot of text to describe a control, consider simplifying your interface design.
+
+**Use sentence case.** Sentence case tends to appear more casual and approachable. If you write complete sentences, omit ending punctuation unless it’s required to be consistent with your app’s style.
+
+**Consider offering context-sensitive tooltips.** For example, you could provide different text for a control’s different states.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/offering-help#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/offering-help#Related)
+
+[Onboarding](https://developer.apple.com/design/human-interface-guidelines/onboarding)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+[Writing](https://developer.apple.com/design/human-interface-guidelines/writing)
+
+[Help menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Help-menu)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/offering-help#Developer-documentation)
+
+[TipKit](https://developer.apple.com/documentation/TipKit)
+
+[`NSHelpManager`](https://developer.apple.com/documentation/AppKit/NSHelpManager) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/offering-help#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/7BCB7D16-5D51-419D-B332-E008219FB631/8293_wide_250x141_1x.jpg) Make features discoverable with TipKit ](https://developer.apple.com/videos/play/wwdc2023/10229)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/offering-help#Change-log)
+
+Date| Changes  
+---|---  
+December 5, 2023| Included visionOS in guidance for creating tooltips.  
+September 12, 2023| Added guidance for creating tips.  
+  

package/templates/.agent/skills/hig-patterns/references/onboarding.md

@@ -0,0 +1,69 @@
+---
+title: "Onboarding | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/onboarding
+
+# Onboarding
+
+Onboarding can help people get a quick start using your app or game.
+
+![A sketch of a waving hand, suggesting a gesture of welcoming. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/044d56043e30ee77f306a8613041311b/patterns-onboarding-intro%402x.png)
+
+Ideally, people can understand your app or game simply by experiencing it, but if onboarding is necessary, design a flow that’s fast, fun, and optional. When available, onboarding occurs after [launching](https://developer.apple.com/design/human-interface-guidelines/launching) is complete — it isn’t part of the launch experience.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/onboarding#Best-practices)
+
+**Teach through interactivity.** People tend to grasp and retain information better when they can actually perform the task they’re learning about instead of just viewing instructional material. As much as possible, provide an interactive onboarding experience where people can safely test an action, discover a feature, or try out a game mechanic.
+
+**Consider providing a collection of context-specific tips instead of a single onboarding flow.** Integrating contextually relevant tips into your experience can help people learn about their current task while they make progress in your app or game. A context-specific tip can also help people learn better because it lets them concentrate on a single action or task before encountering new information. When you have instructional content that refers to a specific area of the interface, display these instructions near that area. For developer guidance, see [TipKit](https://developer.apple.com/documentation/TipKit).
+
+**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.** When onboarding is quick and entertaining, people are more likely to complete it. In contrast, if you try to teach too much, people can feel overwhelmed and may be less likely to remember what they learned.
+
+**If it makes sense to offer a separate tutorial, consider making it optional.** If you let people skip the tutorial when they first launch your app or game, don’t present it again on subsequent launches, but make sure it’s easy for people to find if they want to view it later. For example, you could make the tutorial available in a help, account, or settings area within your app or game.
+
+**Keep onboarding content focused on the experience you provide.** People enter your onboarding flow to learn about your app or game; they don’t need to learn how to use the system or the device.
+
+## [Additional content](https://developer.apple.com/design/human-interface-guidelines/onboarding#Additional-content)
+
+**Briefly display a splash screen if necessary.** If you need to include a splash screen, design a beautiful graphic that communicates succinctly. Aim to display your splash screen just long enough for people to absorb the information at a glance without feeling that it’s delaying their experience.
+
+**Don’t let large downloads hinder onboarding.** People want to start using your app or game immediately after first launching it, whether they participate in an onboarding flow or skip it. Consider including enough media and other content in your software package to prevent people from having to wait for downloads to complete before they can start interacting with your app or game. For guidance, see [Launching](https://developer.apple.com/design/human-interface-guidelines/launching).
+
+**Avoid displaying licensing details within your onboarding flow.** Let the App Store display agreements and disclaimers so people can read them before downloading your app or game. If you must include these items within the onboarding flow, integrate them in a balanced way that doesn’t disrupt the experience.
+
+## [Additional requests](https://developer.apple.com/design/human-interface-guidelines/onboarding#Additional-requests)
+
+**Postpone nonessential setup flows or customization steps.** Provide reasonable default settings so most people can immediately start interacting with your app or game without performing additional configuration.
+
+**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.** In this scenario, making the request during your onboarding flow gives you the opportunity to show people why your app or game needs their permission and the benefits of granting it. Otherwise, present a permission request when people first access the specific function that relies on private data or resources. For guidance, see [Requesting permission](https://developer.apple.com/design/human-interface-guidelines/privacy#Requesting-permission).
+
+**Prefer letting people experience your app or game before prompting them for ratings or purchases.** People can be more likely to respond positively to such requests when they’ve had a chance to become engaged with your app or game.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/onboarding#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/onboarding#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/onboarding#Related)
+
+[Launching](https://developer.apple.com/design/human-interface-guidelines/launching)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+[Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/onboarding#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/BE8FF113-0FE1-40FC-86BF-FE95BE2FF7A5/5027_wide_250x141_1x.jpg) Discoverable design ](https://developer.apple.com/videos/play/wwdc2021/10126)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/48/B27C091C-CF5C-4E42-B1E2-9172615462AB/2724_wide_250x141_1x.jpg) Designing Award Winning Apps and Games ](https://developer.apple.com/videos/play/wwdc2019/802)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/7/2C48F507-180B-4858-BB26-488C234B067F/1920_wide_250x141_1x.jpg) Love at First Launch ](https://developer.apple.com/videos/play/wwdc2017/816)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/onboarding#Change-log)
+
+Date| Changes  
+---|---  
+June 10, 2024| Clarified different approaches to onboarding and added a guideline on displaying a splash screen.  
+June 21, 2023| Updated to include guidance for visionOS.  
+