codehava-agent-kit 1.0.1 → 3.0.0

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

@@ -0,0 +1,50 @@
+---
+title: "Printing | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/printing
+
+# Printing
+
+An iOS, iPadOS, macOS, or visionOS app can integrate system-provided print functionality when it makes sense, presenting custom printer- and document-specific options if necessary.
+
+![A sketch of a printer, suggesting printing. 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/1194b45798f16b503c0a91c6d8ed3ecc/patterns-printing-intro%402x.png)
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/printing#Best-practices)
+
+**Make printing discoverable.** Help people find your print action by placing it in standard system locations. For example, include a Print item in your macOS app’s File menu; in your iOS or iPadOS app, add a toolbar button that opens an [action sheet](https://developer.apple.com/design/human-interface-guidelines/action-sheets). If your macOS app has a toolbar, you might want to put a Print button there, too, but consider making it an optional button that people can add when they customize the toolbar.
+
+**Present a printing option only when it’s possible.** If there’s nothing onscreen to print, or no printers are available, dim the Print item in a macOS app’s File menu and remove the Print action from the Action sheet in an iOS or iPadOS app. If you implement a custom print button, dim or hide it when printing isn’t possible.
+
+**Present relevant printing options.** If it makes sense to offer options like selecting a page range, requesting multiple copies, or printing on both sides — and the printer supports the options — use the system-provided view to present them.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/printing#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or visionOS. Not supported in tvOS or watchOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/printing#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.** By default, the print panel offers several categories of settings, such as Layout, Paper Handling, and Media & Quality. Give your custom category a unique name, such as your app name, and include options that help people have a great print experience in your app. For example, Keynote offers presentation-specific options, like the ability to print presenter notes, slide backgrounds, and skipped slides.
+
+**If your app supports document-specific page settings, consider presenting a page setup dialog.** A _page setup dialog_ includes rarely changed settings for page size, orientation, and scaling that apply to printing a particular document. If this makes sense in your app, avoid implementing features the system already provides. For example, you don’t need to include options like changing the page orientation or printing in reverse order because the system implements these options.
+
+**Make sure interdependencies between options are clear.** For example, if double-sided printing is available, an option to print on transparencies becomes unavailable.
+
+**Separate advanced features from frequently used features.** Consider using a disclosure control to hide advanced options until they’re needed. Label advanced options as _Advanced Options_.
+
+**Consider letting people preview the effect of a setting.** For example, you could update a thumbnail image to show the effect of changing a tone control.
+
+**Consider storing modified settings with the document.** At minimum, it makes sense to store print settings until the document is closed in case people want to print it again.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/printing#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/printing#Related)
+
+[File management](https://developer.apple.com/design/human-interface-guidelines/file-management)
+
+[File menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#File-menu)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/printing#Developer-documentation)
+
+[`UIPrintInteractionController`](https://developer.apple.com/documentation/UIKit/UIPrintInteractionController) — UIKit
+
+[`NSDocument`](https://developer.apple.com/documentation/AppKit/NSDocument) — AppKit
+

package/templates/.agent/skills/hig-patterns/references/ratings-and-reviews.md

@@ -0,0 +1,48 @@
+---
+title: "Ratings and reviews | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews
+
+# Ratings and reviews
+
+People often view the ratings and reviews for an app or game before they download it.
+
+![A sketch of a half-filled star, suggesting a favorability rating. 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/1d5f982affa4088005ecd7c8d6edddff/patterns-ratings-and-reviews-intro%402x.png)
+
+Delivering a great overall experience is the best way to encourage positive ratings and reviews, but it’s also crucial to choose the right time to ask people for feedback. Although every app is different, some possible ways to do this involve looking at how many times or how frequently people launch your app, the number of features someone explores, or the number of tasks they complete.
+
+People can always rate your app within the App Store.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Best-practices)
+
+**Ask for a rating only after people have demonstrated engagement with your app or game.** For example, you might prompt people when they complete a game level or a significant task. Avoid asking for a rating on first launch or during onboarding, because people haven’t had enough time to gain a clear understanding of your app’s value or form an opinion. People may even be more likely to leave negative feedback if they feel an app is asking for a rating before they get a chance to use it.
+
+![An illustration of the UI that appears when a person is prompted to rate an app or game in macOS.](https://docs-assets.developer.apple.com/published/b0aee2c246e2cfd035ba21ed1a2004c3/ratings-and-reviews-ios-alert%402x.png)
+
+**Avoid interrupting people while they’re performing a task or playing a game.** Asking for feedback can disrupt the user experience and feel like a burden. Look for natural breaks or stopping points in your app or game where a rating request is less likely to be bothersome.
+
+**Avoid pestering people.** Repeated rating requests can be irritating, and may even negatively influence people’s opinion of your app. Consider allowing at least a week or two between requests, prompting again after people demonstrate additional engagement with your experience.
+
+**Prefer the system-provided prompt.** iOS, iPadOS, and macOS offer a consistent, nonintrusive way for apps and games to request ratings and reviews. When you identify places in your experience where it makes sense to ask for feedback, the system checks for previous feedback and — if there isn’t any — displays an in-app prompt that asks for a rating and an optional written review. People can supply feedback or dismiss the prompt with a single tap or click; they can also opt out of receiving these prompts for all apps they have installed. The system automatically limits the display of the prompt to three occurrences per app within a 365-day period. For developer guidance, see [`RequestReviewAction`](https://developer.apple.com/documentation/StoreKit/RequestReviewAction).
+
+**Weigh the benefits of resetting your summary rating against the potential disadvantage of showing fewer ratings.** When you release a new version of your app or game, you can reset the summary of individual ratings you received since the last reset. Although resetting means that the ratings reflect the current version, it also tends to result in having fewer ratings overall, which can discourage some people from downloading your app. For developer guidance, see [Reset app summary rating](https://help.apple.com/app-store-connect/#/devfb7e87af8).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Related)
+
+[Ratings, reviews, and responses](https://developer.apple.com/app-store/ratings-and-reviews/)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Developer-documentation)
+
+[`RequestReviewAction`](https://developer.apple.com/documentation/StoreKit/RequestReviewAction) — StoreKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews#Change-log)
+
+Date| Changes  
+---|---  
+September 12, 2023| Added artwork.  
+  

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

@@ -0,0 +1,70 @@
+---
+title: "Searching | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/searching
+
+# Searching
+
+People use various search techniques to find content on their device, within an app, and within a document or file.
+
+![A sketch of a magnifying glass, suggesting the search for information. 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/d80bc4d95013730b824dc7956f912b4d/patterns-searching-intro%402x.png)
+
+To search for content within an app, people generally expect to use a [search field](https://developer.apple.com/design/human-interface-guidelines/search-fields). When it makes sense, you can personalize the search experience by using what you know about how people interact with your app. For example, you might display recent searches, search suggestions, completions, or corrections based on terms people searched earlier in your app.
+
+In some cases, people appreciate the ability to scope a search or filter the results. For example, people might want to search for items by specifying attributes like creation date, file size, or file type. For guidance, see [Scope controls and tokens](https://developer.apple.com/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens). You can also help people find content within an open document or file by implementing ways to find content in a window or page in your iOS, iPadOS, or macOS app.
+
+In iOS, iPadOS, and macOS, Spotlight helps people find content across all apps in the system and on the web. When you index and provide information about your app’s content, people can use Spotlight to find content your app contains without opening it first. For guidance, see [Systemwide search](https://developer.apple.com/design/human-interface-guidelines/searching#Systemwide-search).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/searching#Best-practices)
+
+**If search is important, consider making it a primary action.** For example, in the Apple TV, Photos, and Phone apps in iOS, search occupies a distinct tab in the [tab bar](https://developer.apple.com/design/human-interface-guidelines/tab-bars). In the Notes app, a search field is in the [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars), making search clearly visible and easily accessible.
+
+**Aim to make your app’s content searchable through a single location.** People appreciate having one clearly identified location they can use to find anything in your app that they are looking for. For apps with clearly distinct sections, it may still be useful to offer a local search. For example, search acts as a filter on the current view when searching your Recents and Contacts in the iOS Phone app.
+
+**Use placeholder text to indicate what content is searchable.** For example, the Apple TV app includes the placeholder text _Shows, Movies, and More_.
+
+**Clearly display the current scope of a search.** Use a descriptive placeholder text, a [scope control](https://developer.apple.com/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens), or a title to help reinforce what someone is currently searching. For example, in the Mail app there is always a clear reference to the mailbox someone is searching.
+
+**Provide suggestions to make searching easier.** When you display a personʼs recent searches or offer search suggestions both before and while they’re typing, you can help people search faster and type less. For developer guidance, see [`searchSuggestions(_:)`](https://developer.apple.com/documentation/SwiftUI/View/searchSuggestions\(_:\)).
+
+**Take privacy into consideration before displaying search history.** People might not appreciate having their search history appear where others might see it. Depending on the context, consider providing other ways to narrow the search instead. If you do show search history, provide a way for people to clear it if they want.
+
+## [Systemwide search](https://developer.apple.com/design/human-interface-guidelines/searching#Systemwide-search)
+
+**Make your app’s content searchable in Spotlight.** You can share content with Spotlight by making it indexable and specifying descriptive attributes known as _metadata_. Spotlight extracts, stores, and organizes this information to allow for fast, comprehensive searches.
+
+**Define metadata for custom file types you handle.** Supply a Spotlight File Importer plug-in that describes the types of metadata your file format contains. For developer guidance, see [`CSImportExtension`](https://developer.apple.com/documentation/CoreSpotlight/CSImportExtension).
+
+**Use Spotlight to offer advanced file-search capabilities within the context of your app.** For example, you might include a button that instantly initiates a Spotlight search based on the current selection. You might then display a custom view that presents the search results or a filtered subset of them.
+
+**Prefer using the system-provided open and save views.** The system-provided open and save views generally include a built-in search field that people can use to search and filter the entire system. For related guidance, see [File management](https://developer.apple.com/design/human-interface-guidelines/file-management).
+
+**Implement a Quick Look generator if your app produces custom file types.** A Quick Look generator helps Spotlight and other apps show previews of your documents. For developer guidance, see [Quick Look](https://developer.apple.com/documentation/QuickLook).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/searching#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/searching#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/searching#Related)
+
+[Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/searching#Developer-documentation)
+
+[Adding your app’s content to Spotlight indexes](https://developer.apple.com/documentation/CoreSpotlight/adding-your-app-s-content-to-spotlight-indexes) — Core Spotlight
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/searching#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/C03E6E6D-A32A-41D0-9E50-C3C6059820AA/50ADDE23-F013-4993-8B1D-09368B4BD5F4/9259_wide_250x141_1x.jpg) Support semantic search with Core Spotlight ](https://developer.apple.com/videos/play/wwdc2024/10131)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/6E076CE0-7DDF-4471-B6F0-005ADF9C7960/6500_wide_250x141_1x.jpg) What’s new in iPad app design ](https://developer.apple.com/videos/play/wwdc2022/10009)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/D45C244B-2038-4692-99A0-6131ED5FD984/5084_wide_250x141_1x.jpg) Craft search experiences in SwiftUI ](https://developer.apple.com/videos/play/wwdc2021/10176)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/searching#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Updated best practices with general guidance from Search fields, and reorganized guidance for systemwide search.  
+  

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

@@ -0,0 +1,84 @@
+---
+title: "Settings | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/settings
+
+# Settings
+
+People expect apps and games to just work, but they also appreciate having ways to customize the experience to fit their needs.
+
+![A sketch of a gear, suggesting configuration. 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/38706162753c93aa16bfa6295987c33a/patterns-settings-intro%402x.png)
+
+On all Apple platforms, the system-provided Settings app lets people adjust things like the overall appearance of the system, network connections, account details, accessibility requirements, and language and region settings. On some platforms, the system-provided Settings app can also include settings for specific apps and games, often letting people adjust whether the app or game can access location information, use device features like microphone or camera, and integrate with system features like notifications, Siri, or Search.
+
+When necessary, you can provide a custom settings area within your app or game to offer general settings that affect your overall experience, like interface style or game-saving behavior. If you need to offer settings that affect only a specific task, you can provide these options within the task itself, so people don’t have to leave the experience to customize it.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/settings#Best-practices)
+
+**Aim to provide default settings that give the best experience to the largest number of people.** For example, you can automatically maximize performance for the device your game is running on instead of asking players to make this choice after your game launches (for developer guidance, see [Improving your game’s graphics performance and settings](https://developer.apple.com/documentation/Metal/improving-your-games-graphics-performance-and-settings)). When you choose appropriate default settings, people may not have to make any adjustments before they can start enjoying your app or game.
+
+**Minimize the number of settings you offer.** Although people appreciate having control over an app or game, too many settings can make the experience feel less approachable, while also making it hard to find a particular setting.
+
+**Make settings available in ways people expect.** For example, when a physical keyboard is connected, people often use the standard Command-Comma (,) keyboard shortcut to open an app’s settings, whereas in a game, players often use the Esc (Escape) key.
+
+**Avoid using settings to ask for setup information you can get in other ways.** For example, a game can automatically detect a connected controller or accessory instead of asking the player to identify it; an app can detect whether people are currently using Dark Mode.
+
+**Respect people’s systemwide settings and avoid including redundant versions of them in your custom settings area.** People expect to use the system-provided Settings app to manage global options like accessibility accommodations, scrolling behavior, and authentication methods, and they expect all apps and games to adhere to their choices. Including custom versions of global options in your settings area is likely to confuse people because it implies that systemwide settings may not apply to your app or game and that changing your custom version of a global setting may affect other apps and games, too.
+
+## [General settings](https://developer.apple.com/design/human-interface-guidelines/settings#General-settings)
+
+**Put general, infrequently changed settings in your custom settings area.** People must suspend what they’re doing to open an app’s or game’s settings area, so you want to include options that people don’t need to change all the time. For example, an app might list options for adjusting window configuration; a game might let players specify game-saving behavior or keyboard mappings; both apps and games might offer options related to people’s accounts.
+
+## [Task-specific options](https://developer.apple.com/design/human-interface-guidelines/settings#Task-specific-options)
+
+**When possible, prefer letting people modify task-specific options without going to your settings area.** For example, if people can adjust things like showing or hiding parts of the current view, reordering a collection of items, or filtering a list, make these options available in the screens they affect, where they’re discoverable and convenient. Putting this type of option in a separate settings area disconnects it from its context, requiring people to suspend their task to make adjustments, and often hiding the results until people resume the task.
+
+Note
+
+In games, players tend to adjust their approach to a specific task as part of the gameplay, not as a settings option to change.
+
+## [System settings](https://developer.apple.com/design/human-interface-guidelines/settings#System-settings)
+
+**Add only the most rarely changed options to the system-provided Settings app.** If it makes sense to add your app’s or game’s settings to the system-provided Settings app, consider providing a button that opens it directly from your interface.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/settings#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, tvOS, or visionOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/settings#macOS)
+
+When people choose the Settings item in your app’s or game’s App menu, your custom settings window opens. Typically, a custom settings window contains a toolbar that includes buttons for switching between views — called _panes_ — that each contain a group of related settings.
+
+**Include a settings item in the[App menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#App-menu).** Avoid adding settings buttons to a window’s toolbar, because doing so decreases the space available for essential commands that people use frequently. If you provide document-level options, add this item to your app’s [File menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#File-menu).
+
+**Dim a settings window’s minimize and maximize buttons.** It’s quick to open a custom settings window using the standard Command–Comma (,) keyboard command, so there’s no need to keep the window in the Dock, and because a settings window accommodates the size of the current pane, people don’t need to expand the window to see more.
+
+**In your settings window, use a noncustomizable toolbar that remains visible and always indicates the active toolbar button.** A settings window’s toolbar identifies the areas people can customize and helps people navigate among those areas. People rely on a stable settings interface to help them find what they need.
+
+**Update the window’s title to reflect the currently visible pane.** If your settings window doesn’t have multiple panes, use the title _App Name_ Settings.
+
+**Restore the most recently viewed pane.** People often adjust related settings more than once, so it can be convenient when a settings window opens to the last pane people used.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/settings#watchOS)
+
+In watchOS, apps and games don’t add custom settings to the system-provided Settings app. As an alternative, consider making a small number of essential options available at the bottom of the main view or letting people use a More menu to reconfigure objects.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/settings#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/settings#Related)
+
+[Onboarding](https://developer.apple.com/design/human-interface-guidelines/onboarding)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/settings#Developer-documentation)
+
+[`Settings`](https://developer.apple.com/documentation/SwiftUI/Settings) — SwiftUI
+
+[`UserDefaults`](https://developer.apple.com/documentation/Foundation/UserDefaults) — Foundation
+
+[Preference Panes](https://developer.apple.com/documentation/PreferencePanes)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/settings#Change-log)
+
+Date| Changes  
+---|---  
+June 10, 2024| Reorganized some guidance into new topics and added game-specific examples.  
+  

package/templates/.agent/skills/hig-patterns/references/undo-and-redo.md

@@ -0,0 +1,58 @@
+---
+title: "Undo and redo | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/undo-and-redo
+
+# Undo and redo
+
+Undo and redo gives people easy ways to reverse many types of actions, which can also help people explore and experiment safely as they learn a new interface or task.
+
+![A sketch of an arrow that starts right, curves upward, and points to the left, suggesting a return to the start. 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/768e64b5954af63fd6f4e9e4a3c5275a/patterns-undo-redo-intro%402x.png)
+
+People expect undo and redo to let them reverse their recent actions, so they’re likely to try undoing — often multiple times — until something changes. In a situation like this, people might not remember which of their previous actions an undo is targeting, which can lead to unintended changes and frustration. To help people remain in control, it’s essential to help people predict the outcome of undoing and redoing and to highlight the results.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Best-practices)
+
+**Help people predict the results of undo and redo as much as possible.** On iPhone, for example, you can describe the result in the alert that displays when people shake the device, giving them the option of performing the undo or canceling it. If you provide undo and redo menu items, you can modify the menu item labels to identify the result. For example, a document-based app might use menu item labels like Undo Typing or Redo Bold.
+
+**Show the results of an undo or redo.** Sometimes, the most recent action that people want to undo affects content or an area that’s no longer visible. In cases like this, it’s crucial to highlight the result of each undo and redo to keep people from thinking that the action had no effect, which can lead them to perform it repeatedly. For example, if people undo after deleting a paragraph in a document area that’s no longer onscreen, you might scroll the document to show the restored paragraph.
+
+**Let people undo multiple times.** Avoid placing unnecessary limits on the number of times people can undo or redo. People generally expect to undo every action they’ve performed since taking a logical step like opening a document or saving their work.
+
+**Consider giving people the option to revert multiple changes at once.** In some scenarios, people might appreciate the ability to undo a batch of discrete but related actions — like incremental adjustments to a single property or attribute — so they don’t have to undo each individual adjustment. In other cases, it can make sense to give people a convenient way to undo all the changes they made since opening a document or saving their work.
+
+**Provide undo and redo buttons only when necessary.** People generally expect to initiate undo and redo in system-supported ways, such as choosing the items in a macOS app’s Edit menu, using keyboard shortcuts on a Mac or iPad, or shaking their iPhone. If it’s important to provide dedicated undo and redo buttons in your app, use the standard system-provided symbols and put the buttons in a toolbar.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Platform-considerations)
+
+ _No additional considerations for visionOS. Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#iOS-iPadOS)
+
+**Avoid redefining standard gestures for undo and redo.** For example, people can use a three-finger swipe to initiate an undo or redo, or shake their iPhone. As with all standard gestures, redefining them in your interface runs the risk of confusing people and making your experience unpredictable.
+
+**Briefly and precisely describe the operation to be undone or redone.** The undo and redo alert title automatically includes a prefix of “Undo ” or “Redo ” (including the trailing space). You need to provide an additional word or two that describes what’s being undone or redone, to appear after this prefix. For example, you might create alert titles such as “Undo Name” or “Redo Address Change.”
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#macOS)
+
+**Place undo and redo commands in the Edit menu and support the standard keyboard shortcuts.** Mac users expect to find undo and redo at the top of the Edit menu; they also expect to use Command–Z and Shift–Command–Z to perform undo and redo, respectively.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Related)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+[Pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices)
+
+[Standard keyboard shortcuts](https://developer.apple.com/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts)
+
+[Edit menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Edit-menu)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Developer-documentation)
+
+[`UndoManager`](https://developer.apple.com/documentation/Foundation/UndoManager) — Foundation
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/7/2546ECBD-6443-41EC-921D-6429026F8B67/1700_wide_250x141_1x.jpg) Essential Design Principles ](https://developer.apple.com/videos/play/wwdc2017/802)
+

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

@@ -0,0 +1,76 @@
+---
+title: "Workouts | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/workouts
+
+# Workouts
+
+A great workout or fitness experience encourages people to engage with their current activity and helps them track their progress on their devices.
+
+![A sketch of a person running, suggesting exercise. 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/94f9af416ac4b86e302f1f487b8a1372/patterns-workouts-intro%402x.png)
+
+People can wear their Apple Watch during many types of workouts, and they might carry their iPhone or iPad during fitness activities like walking, wheelchair pushing, and running. In contrast, people tend to use their larger or more stationary devices like iPad Pro, Mac, and Apple TV to participate in live or recorded workout sessions by themselves or with others.
+
+You can create a workout experience for Apple Watch, iPhone, or iPad that helps people reach their goals by leveraging activity data from the device and using familiar components to display fitness metrics.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/workouts#Best-practices)
+
+**In a watchOS fitness app, use workout sessions to provide useful data and relevant controls.** During a fitness app’s active workout sessions, watchOS continues to display the app as time passes between wrist raises, so it’s important to provide the workout data people are most likely to care about. For example, you might show elapsed or remaining time, calories burned, or distance traveled, and offer relevant controls like lap or interval markers.
+
+**Avoid distracting people from a workout with information that’s not relevant.** For example, people don’t need to review the list of workouts you offer or access other parts of your app while they’re working out. Here is an arrangement that many watchOS workout apps use, including Workout:
+
+![A screenshot of the leftmost Workout screen for an Outdoor Walk workout. Clockwise from the top-left corner are the End, Resume, New, and Segment buttons.](https://docs-assets.developer.apple.com/published/f893039e593af4d8e40eb6d374dfc6a3/workouts-large-buttons%402x.png)
+
+Large buttons that control the in-progress session — such as End, Resume, and New — appear on the leftmost screen.
+
+![A screenshot of the middle Workout screen for an Outdoor Walk workout. Five lines of data are visible. From the top, the screen shows the elapsed time, the active calories, the current heart rate, the average pace, and the elevation.](https://docs-assets.developer.apple.com/published/8de838390249b16301bfc5495947da37/workouts-metrics%402x.png)
+
+Metrics and other data appear on a dedicated screen that people can read at a glance.
+
+![A screenshot of the rightmost Workout screen, which shows information about the music currently playing.](https://docs-assets.developer.apple.com/published/acc22020a6613bd6558ce8ea836aa156/workouts-media-playback%402x.png)
+
+If supported, media playback controls appear on the rightmost screen.
+
+**Use a distinct visual appearance to indicate an active workout.** During a workout, people appreciate being able to recognize an active session at a glance. The metrics page can be a good way to show that a session is active because the values update in real time. In addition to displaying updating values, you can further distinguish the metrics screen by using a unique layout.
+
+**Provide workout controls that are easy to find and tap.** In addition to making it easy for people to pause, resume, and stop a workout, be sure to provide clear feedback that indicates when a session starts or stops.
+
+**Help people understand the health information your app records if sensor data is unavailable during a workout.** For example, water may prevent a heart-rate measurement, but your app can still record data like the distance people swam and the number of calories they burned. If your app supports the _Swimming_ or _Other_ workout types, explain the situation using language that’s similar to the language used in the system-provided Workout app, as shown below:
+
+| Example text from the Workout app  
+---|---  
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)| GPS is not used during a Pool Swim, and water may prevent a heart-rate measurement, but Apple Watch will still track your calories, laps, and distance using the built-in accelerometer.  
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)| In this type of workout, you earn the calorie equivalent of a brisk walk anytime sensor readings are unavailable.  
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)| GPS will only provide distance when you do a freestyle stroke. Water might prevent a heart-rate measurement, but calories will still be tracked using the built-in accelerometer.  
+  
+**Provide a summary at the end of a session.** A summary screen confirms that a workout is finished and displays the recorded information. Consider enhancing the summary by including Activity rings, so that people can easily check their current progress.
+
+**Discard extremely brief workout sessions.** If a session ends a few seconds after it starts, either discard the data automatically or ask people if they want to record the data as a workout.
+
+**Make sure text is legible for when people are in motion.** When a session requires movement, use large font sizes, high-contrast colors, and arrange text so that the most important information is easy to read.
+
+**Use Activity rings correctly.** The Activity rings view is an Apple-designed element featuring one or more rings whose colors and meanings match those in the Activity app. Use them only for their documented purpose.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/workouts#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or watchOS. Not supported in macOS, tvOS, or visionOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/workouts#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/workouts#Related)
+
+[Activity rings](https://developer.apple.com/design/human-interface-guidelines/activity-rings)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/workouts#Developer-documentation)
+
+[WorkoutKit](https://developer.apple.com/documentation/WorkoutKit)
+
+[Workouts and activity rings](https://developer.apple.com/documentation/HealthKit/workouts-and-activity-rings) — HealthKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/workouts#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/12499BF9-8217-4A56-81CA-5E7CB66904DD/9856_wide_250x141_1x.jpg) Track workouts with HealthKit on iOS and iPadOS ](https://developer.apple.com/videos/play/wwdc2025/322)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/50551741-78CD-4E8A-9550-7D0EC29D7882/8035_wide_250x141_1x.jpg) Build custom workouts with WorkoutKit ](https://developer.apple.com/videos/play/wwdc2023/10016)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/30D3C2CB-B24D-467A-9B20-A369641E966F/4850_wide_250x141_1x.jpg) Build a workout app for Apple Watch ](https://developer.apple.com/videos/play/wwdc2021/10009)
+