bps-kit 1.0.1 → 1.0.3

package/templates/vault/hig-patterns/references/searching.md

@@ -1,70 +0,0 @@
----
-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/vault/hig-patterns/references/settings.md

@@ -1,84 +0,0 @@
----
-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/vault/hig-patterns/references/undo-and-redo.md

@@ -1,58 +0,0 @@
----
-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/vault/hig-patterns/references/workouts.md

@@ -1,76 +0,0 @@
----
-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)
-

package/templates/vault/hig-platforms/SKILL.md

@@ -1,81 +0,0 @@
----
-name: hig-platforms
-description: Apple Human Interface Guidelines for platform-specific design.
-risk: unknown
-source: community
-date_added: '2026-02-27'
----
-
-# Apple HIG: Platform Design
-
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
-
-## Key Principles
-
-1. **Each platform has a distinct identity.** Do not port designs between platforms. Respect each platform's conventions, interaction models, and user expectations.
-
-2. **iOS: touch-first.** Direct manipulation on a handheld screen. Optimize for one-handed use. Navigation uses tab bars and push/pop stacks.
-
-3. **iPadOS: expanded canvas.** Support Split View, Slide Over, and Stage Manager. Use sidebars and multi-column layouts. Support pointer and keyboard alongside touch.
-
-4. **macOS: pointer and keyboard.** Dense information display is acceptable. Use menu bars, toolbars, and keyboard shortcuts extensively. Windows are resizable with precise control.
-
-5. **tvOS: remote and focus.** Viewed from a distance. Design for the Siri Remote with focus-based navigation. Large text, simple layouts, linear navigation.
-
-6. **visionOS: spatial interaction.** 3D environment using windows, volumes, and spaces. Eye tracking for targeting, indirect gestures for interaction. Respect ergonomic comfort zones.
-
-7. **watchOS: glanceable and brief.** Information consumable at a glance. Brief interactions. Digital Crown, haptics, and complications for timely content.
-
-8. **Games: own paradigm.** Free to define in-game interaction models, but still respect platform conventions for system interactions (notifications, accessibility, controllers).
-
-## Reference Index
-
-| Reference | Topic | Key content |
-|---|---|---|
-| [designing-for-ios.md](references/designing-for-ios.md) | iOS | Touch, tab bars, navigation stacks, gestures, screen sizes, safe areas |
-| [designing-for-ipados.md](references/designing-for-ipados.md) | iPadOS | Multitasking, sidebars, pointer, keyboard, Apple Pencil, Stage Manager |
-| [designing-for-macos.md](references/designing-for-macos.md) | macOS | Menu bars, toolbars, window management, keyboard shortcuts, dense layouts, Dock |
-| [designing-for-tvos.md](references/designing-for-tvos.md) | tvOS | Focus engine, Siri Remote, lean-back experience, content-forward, parallax |
-| [designing-for-visionos.md](references/designing-for-visionos.md) | visionOS | Spatial computing, windows/volumes/spaces, eye tracking, hand gestures, depth |
-| [designing-for-watchos.md](references/designing-for-watchos.md) | watchOS | Glanceable UI, Digital Crown, complications, notifications, haptics |
-| [designing-for-games.md](references/designing-for-games.md) | Games | Controllers, immersive experiences, platform-specific conventions, accessibility |
-
-## Decision Framework
-
-1. **Identify the primary use context.** On the go (iOS/watchOS), at a desk (macOS), on the couch (tvOS), spatial environment (visionOS)?
-
-2. **Match input to interaction.** Touch for direct manipulation, pointer for precision, gaze+gesture for spatial, Digital Crown for quick scrolling, remote for focus navigation.
-
-3. **Adapt, don't replicate.** A macOS sidebar becomes a tab bar on iPhone. A visionOS volume has no equivalent on watchOS. Translate intent, not implementation.
-
-4. **Leverage platform strengths.** Live Activities on iOS, Desktop Widgets on macOS, complications on watchOS, immersive spaces on visionOS.
-
-5. **Maintain brand consistency** while respecting each platform's visual language and interaction patterns.
-
-## Output Format
-
-1. **Platform-specific recommendations** citing relevant HIG sections.
-2. **Platform differences table** comparing navigation, input, layout, and conventions.
-3. **Implementation notes** per platform including recommended APIs and adaptation strategies.
-
-## Questions to Ask
-
-1. Which platforms are you targeting?
-2. New app or adapting an existing one? If existing, which platform is the base?
-3. SwiftUI or UIKit/AppKit?
-4. Need to support older OS versions?
-5. Primary use context? (On the go, desk, couch, spatial, glanceable?)
-
-## Related Skills
-
-- **hig-foundations** -- Shared principles (color, typography, accessibility, layout) across platforms
-- **hig-patterns** -- Interaction patterns that manifest differently per platform
-- **hig-components-layout** -- Navigation structures (tab bars, sidebars, split views) that vary by platform
-- **hig-components-content** -- Content display that adapts across platforms
-
----
-
-*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.

package/templates/vault/hig-platforms/references/designing-for-games.md

@@ -1,159 +0,0 @@
----
-title: "Designing for games | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/designing-for-games
-
-# Designing for games
-
-When people play your game on an Apple device, they dive into the world you designed while relying on the platform features they love.
-
-![A stylized representation of a game controller shown on top of a grid. The image is overlaid with rectangular and circular grid lines and is tinted green to subtly reflect the green in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/87a9000504347b999d742d13b3b73635/platforms-games-intro%402x.png)
-
-As you create or adapt a game for Apple platforms, learn how to integrate the fundamental platform characteristics and patterns that help your game feel at home on all Apple devices. To learn what makes each platform unique, see [Designing for iOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-ios), [Designing for iPadOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-ipados), [Designing for macOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-macos), [Designing for tvOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-tvos), [Designing for visionOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos), and [Designing for watchOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos). For developer guidance, see [Games Pathway](https://developer.apple.com/games/pathway/).
-
-## [Jump into gameplay](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Jump-into-gameplay)
-
-**Let people play as soon as installation completes.** You don’t want a player’s first experience with your game to be waiting for a lengthy download. Include as much playable content as you can in your game’s initial installation while keeping the download time to 30 minutes or less. Download additional content in the background. For guidance, see [Loading](https://developer.apple.com/design/human-interface-guidelines/loading).
-
-**Provide great default settings.** People appreciate being able to start playing without first having to change a lot of settings. Use information about a player’s device to choose the best defaults for your game, such as the device resolution that makes your graphics look great, automatic recognition of paired accessories and game controllers, and the player’s accessibility settings. Also, make sure your game supports the platform’s most common interaction methods. For guidance, see [Settings](https://developer.apple.com/design/human-interface-guidelines/settings).
-
-**Teach through play.** Players often learn better when they discover new information and mechanics in the context of your game’s world, so it can work well to integrate configuration and onboarding flows into a playable tutorial that engages people quickly and helps them feel successful right away. If you also have a written tutorial, consider offering it as a resource players can refer to when they have questions instead of making it a prerequisite for gameplay. For guidance, see [Onboarding](https://developer.apple.com/design/human-interface-guidelines/onboarding).
-
-**Defer requests until the right time.** You don’t want to bombard people with too many requests before they start playing, but if your game uses certain sensors on an Apple device or personalizes gameplay by accessing data like hand-tracking, you must first get the player’s permission (for guidance, see [Privacy](https://developer.apple.com/design/human-interface-guidelines/privacy)). To help people understand why you’re making such a request, integrate it into the scenario that requires the data. For example, you could ask permission to track a player’s hands between an initial cutscene and the first time they can use their hands to control the action. Also, make sure people spend quality time with your game before you ask them for a rating or review (for guidance, see [Ratings and reviews](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews)).
-
-[![A sketch of a square containing an arrow pointing to the upper-right corner, suggesting a transition to a new state. The image is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/95c588c36ab492f99a5a71addbabef12/patterns-launching-thumbnail%402x.png) Launching ](https://developer.apple.com/design/human-interface-guidelines/launching)
-
-[![A sketch of a waving hand, suggesting a gesture of welcoming. The image is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/d95e8d3a568083918565701d3fe5360e/patterns-onboarding-thumbnail%402x.png) Onboarding ](https://developer.apple.com/design/human-interface-guidelines/onboarding)
-
-[![A sketch of a spinning indeterminate activity indicator, suggesting data loading. The image is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/d3c4485e4c81890440c23e3f64d5511e/patterns-loading-thumbnail%402x.png) Loading ](https://developer.apple.com/design/human-interface-guidelines/loading)
-
-## [Look stunning on every display](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Look-stunning-on-every-display)
-
-**Make sure text is always legible.** When game text is hard to read, people can struggle to follow the narrative, understand important instructions and information, and stay engaged in the experience. To keep text comfortably legible on each device, ensure that it contrasts well with the background and uses at least the recommended minimum text size in each platform. For guidance, see [Typography](https://developer.apple.com/design/human-interface-guidelines/typography); for developer guidance, see [Adapting your game interface for smaller screens](https://developer.apple.com/documentation/Metal/adapting-your-game-interface-for-smaller-screens).
-
-Platform| Default text size| Minimum text size  
----|---|---  
-iOS, iPadOS| 17 pt| 11 pt  
-macOS| 13 pt| 10 pt  
-tvOS| 29 pt| 23 pt  
-visionOS| 17 pt| 12 pt  
-watchOS| 16 pt| 12 pt  
-  
-**Make sure buttons are always easy to use.** Buttons that are too small or too close together can frustrate players and make gameplay less fun. Each platform defines a recommended minimum button size based on its default interaction method. For example, buttons in iOS must be at least 44x44 pt to accommodate touch interaction. For guidance, see [Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons).
-
-Platform| Default button size| Minimum button size  
----|---|---  
-iOS, iPadOS| 44x44 pt| 28x28 pt  
-macOS| 28x28 pt| 20x20 pt  
-tvOS| 66x66 pt| 56x56 pt  
-visionOS| 60x60 pt| 28x28 pt  
-watchOS| 44x44 pt| 28x28 pt  
-  
-**Prefer resolution-independent textures and graphics.** If creating resolution-independent assets isn’t possible, match the resolution of your game to the resolution of the device. In visionOS, prefer vector-based art that can continue to look good when the system dynamically scales it as people view it from different distances and angles. For guidance, see [Images](https://developer.apple.com/design/human-interface-guidelines/images).
-
-**Integrate device features into your layout.** For example, a device may have rounded corners or a camera housing that can affect parts of your interface. To help your game look at home on each device, accommodate such features during layout, relying on platform-provided safe areas when possible (for developer guidance, see [Positioning content relative to the safe area](https://developer.apple.com/documentation/UIKit/positioning-content-relative-to-the-safe-area)). For guidance, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout); for templates that include safe-area guides, see [Apple Design Resources](https://developer.apple.com/design/resources/).
-
-**Make sure in-game menus adapt to different aspect ratios.** Games need to look good and behave well at various aspect ratios, such as 16:10, 19.5:9, and 4:3. In particular, in-game menus need to remain legible and easy to use on every device — and, if you support them, in both orientations on iPhone and iPad — without obscuring other content. To help ensure your in-game menus render correctly, consider using dynamic layouts that rely on relative constraints to adjust to different contexts. Avoid fixed layouts as much as possible, and aim to create a custom, device-specific layout only when necessary. For guidance, see [In-game menus](https://developer.apple.com/design/human-interface-guidelines/menus#In-game-menus).
-
-**Design for the full-screen experience.** People often enjoy playing a game in a distraction-free, full-screen context. In macOS, iOS, and iPadOS, full-screen mode lets people hide other apps and parts of the system UI; in visionOS, a game running in a Full Space can completely surround people, transporting them somewhere else. For guidance, see [Going full screen](https://developer.apple.com/design/human-interface-guidelines/going-full-screen).
-
-[![A sketch of a small rectangle in the upper-left quadrant of a larger rectangle, suggesting the position of a user interface element within a window. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/0db27821e97ac9613ac0cc103892a10d/foundations-layout-thumbnail%402x.png) Layout ](https://developer.apple.com/design/human-interface-guidelines/layout)
-
-[![A sketch of a small letter A to the left of a large letter A, suggesting the use of typography to convey hierarchical information. The image is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/30a9c2adbbfa1602133dcfb2f5bfeaab/foundations-typography-thumbnail%402x.png) Typography ](https://developer.apple.com/design/human-interface-guidelines/typography)
-
-[![A sketch of two outward-pointing arrows arranged in a vertical line extending from the upper-left to the bottom-right, suggesting expansion. The image is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/335e1e0476ff4830a1a4add07fb016a0/patterns-going-full-screen-thumbnail%402x.png) Going full screen ](https://developer.apple.com/design/human-interface-guidelines/going-full-screen)
-
-## [Enable intuitive interactions](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Enable-intuitive-interactions)
-
-**Support each platform’s default interaction method.** For example, people generally use touch to play games on iPhone; on a Mac, players tend to expect keyboard and mouse or trackpad support; and in a visionOS game, people expect to use their eyes and hands while making indirect and direct gestures. As you work to ensure that your game supports each platform’s default interaction method, pay special attention to control sizing and menu behavior, especially when bringing your game from a pointer-based context to a touch-based one.
-
-Platform| Default interaction methods| Additional interaction methods  
----|---|---  
-iOS| Touch| Game controller  
-iPadOS| Touch| Game controller, keyboard, mouse, trackpad, Apple Pencil  
-macOS| Keyboard, mouse, trackpad| Game controller  
-tvOS| Remote| Game controller, keyboard, mouse, trackpad  
-visionOS| Touch| Game controller, keyboard, mouse, trackpad, spatial game controller  
-watchOS| Touch| –  
-  
-**Support physical game controllers, while also giving people alternatives.** Every platform except watchOS supports physical game controllers. Although the presence of a game controller makes it straightforward to port controls from an existing game and handle complex control mappings, recognize that not every player can use a physical game controller. To make your game available to as many players as possible, also offer alternative ways to interact with your game. For guidance, see [Physical controllers](https://developer.apple.com/design/human-interface-guidelines/game-controls#Physical-controllers).
-
-**Offer touch-based game controls that embrace the touchscreen experience on iPhone and iPad.** In iOS and iPadOS, your game can allow players to interact directly with game elements, and to control the game using virtual controls that appear on top of your game content. For design guidance, see [Touch controls](https://developer.apple.com/design/human-interface-guidelines/game-controls#Touch-controls).
-
-[![A sketch of a D-pad control from a game controller, suggesting gameplay. The image is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/36867292ccfd45e0f937f522d7e214f7/inputs-game-controls-thumbnail%402x.png) Game controls ](https://developer.apple.com/design/human-interface-guidelines/game-controls)
-
-[![A sketch of a pointing hand swiping in a curved motion toward the right, suggesting touch interaction with a device. The image is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/ca100cc13bcc2fbb7168bebc1da95af8/inputs-gestures-thumbnail%402x.png) Gestures ](https://developer.apple.com/design/human-interface-guidelines/gestures)
-
-[![A sketch of an arrow-shaped pointer, suggesting use of a mouse or trackpad. The image is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/69b91fbe2b281f7b638d380a3a6aa416/inputs-pointing-devices-thumbnail%402x.png) Pointing devices ](https://developer.apple.com/design/human-interface-guidelines/pointing-devices)
-
-## [Welcome everyone](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Welcome-everyone)
-
-**Prioritize perceivability.** Make sure people can perceive your game’s content whether they use sight, hearing, or touch. For example, avoid relying solely on color to convey an important detail, or providing a cutscene that doesn’t include descriptive subtitles or offer other ways to read the content. For specific guidance, see:
-
-  * Text sizes
-
-  * Color and effects
-
-  * Motion
-
-  * Interactions
-
-  * Buttons
-
-
-
-
-**Help players personalize their experience.** Players have a variety of preferences and abilities that influence their interactions with your game. Because there’s no universal configuration that suits everyone, give players the ability to customize parameters like type size, game control mapping, motion intensity, and sound balance. You can take advantage of built-in [Apple accessibility technologies](https://developer.apple.com/accessibility/) to support accessibility personalizations, whether you’re using system frameworks or [Unity plug-ins](https://github.com/Apple/UnityPlugins).
-
-**Give players the tools they need to represent themselves.** If your game encourages players to create avatars or supply names or descriptions, support the spectrum of self-identity and provide options that represent as many human characteristics as possible.
-
-**Avoid stereotypes in your stories and characters.** Ask yourself whether you’re depicting game characters and scenarios in a way that perpetuates real-life stereotypes. For example, does your game depict enemies as having a certain race, gender, or cultural heritage? Review your game to uncover and remove biases and stereotypes and — if references to real-life cultures and languages are necessary — be sure they’re respectful.
-
-[![A sketch of the Accessibility icon. The image is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/8b7b11d06dd958f4e9449f0a5acdadbd/foundations-accessibility-thumbnail%402x.png) Accessibility ](https://developer.apple.com/design/human-interface-guidelines/accessibility)
-
-[![A sketch of two people, suggesting inclusion. The image is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/bbb606721d228138791654cb9f6f426c/foundations-inclusion-thumbnail%402x.png) Inclusion ](https://developer.apple.com/design/human-interface-guidelines/inclusion)
-
-## [Adopt Apple technologies](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Adopt-Apple-technologies)
-
-**Integrate Game Center to help players discover your game across their devices and connect with their friends.** [Game Center](https://developer.apple.com/game-center/) is Apple’s social gaming network, available on all platforms. Game Center lets players keep track of their progress and achievements and allows you to set up leaderboards, challenges, and multiplayer activities in your game. For design guidance, see [Game Center](https://developer.apple.com/design/human-interface-guidelines/game-center); for developer guidance, see [GameKit](https://developer.apple.com/documentation/GameKit).
-
-**Let players pick up their game on any of their devices.** People often have a single iCloud account that they use across multiple Apple devices. When you support [GameSave](https://developer.apple.com/documentation/GameSave), you can help people save their game state and start back up exactly where they left off on a different device.
-
-**Support haptics to help players feel the action.** When you adopt Core Haptics, you can compose and play custom haptic patterns, optionally combined with custom audio content. Core Haptics is available in iOS, iPadOS, tvOS, and visionOS, and supported on many game controllers. For guidance, see [Playing haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics); for developer guidance, see [Core Haptics](https://developer.apple.com/documentation/CoreHaptics) and [Playing Haptics on Game Controllers](https://developer.apple.com/documentation/CoreHaptics/playing-haptics-on-game-controllers).
-
-**Use Spatial Audio to immerse players in your game’s soundscape.** Providing multichannel audio can help your game’s audio adapt automatically to the current device, enabling an immersive Spatial Audio experience where supported. For guidance, see [Playing audio > visionOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#visionOS); for developer guidance, see [Explore Spatial Audio](https://developer.apple.com/news/?id=fakg1z5b).
-
-**Take advantage of Apple technologies to enable unique gameplay mechanics.** For example, you can integrate technologies like augmented reality, machine learning, and [HealthKit](https://developer.apple.com/documentation/HealthKit), and request access to location data and functionality like camera and microphone. For a full list of Apple technologies, features, and services, see [Technologies](https://developer.apple.com/design/human-interface-guidelines/technologies).
-
-[![A sketch of the Game Center icon. The image is tinted blue to subtly reflect the blue in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/304edbb771279f5c096419df2cd735fe/technologies-game-center-thumbnail%402x.png) Game Center ](https://developer.apple.com/design/human-interface-guidelines/game-center)
-
-[![A sketch of the iCloud icon. The image is tinted blue to subtly reflect the blue in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/2b14682c9fa6e5d71042fa722c12bb3f/technologies-icloud-thumbnail%402x.png) iCloud ](https://developer.apple.com/design/human-interface-guidelines/icloud)
-
-[![A sketch of an add button, suggesting the purchase of additional digital assets within an app. The image is tinted blue to subtly reflect the blue in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/de58b03338460608880147558546707a/technologies-in-app-purchase-thumbnail%402x.png) In-app purchase ](https://developer.apple.com/design/human-interface-guidelines/in-app-purchase)
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Related)
-
-[Game Center](https://developer.apple.com/design/human-interface-guidelines/game-center)
-
-[Game controls](https://developer.apple.com/design/human-interface-guidelines/game-controls)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Developer-documentation)
-
-[Games Pathway](https://developer.apple.com/games/get-started/)
-
-[Create games for Apple platforms](https://developer.apple.com/games/)
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/6C097D36-BE91-4B04-854A-E6264DA86F15/9890_wide_250x141_1x.jpg) Level up your games ](https://developer.apple.com/videos/play/wwdc2025/209)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/C03E6E6D-A32A-41D0-9E50-C3C6059820AA/2DB746B8-E0B0-4ED1-B250-902DB7A0F3E7/9196_wide_250x141_1x.jpg) Design advanced games for Apple platforms ](https://developer.apple.com/videos/play/wwdc2024/10085)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/designing-for-games#Change-log)
-
-Date| Changes  
----|---  
-June 9, 2025| Updated guidance for touch-based controls and Game Center.  
-June 10, 2024| New page.  
-