bps-kit 1.0.1 → 1.0.3

package/templates/vault/hig-inputs/references/gestures.md

@@ -1,208 +0,0 @@
----
-title: "Gestures | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/gestures
-
-# Gestures
-
-A gesture is a physical motion that a person uses to directly affect an object in an app or game on their device.
-
-![A sketch of a pointing hand swiping in a curved motion toward the right, suggesting touch interaction with a device. The image is overlaid with rectangular and circular grid lines and is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/21ef165b3e1da4255ee2a9a55796afc0/inputs-gestures-intro%402x.png)
-
-Depending on the device they’re using, people can make gestures on a touchscreen, in the air, or on a range of input devices such as a trackpad, mouse, remote, or game controller that includes a touch surface.
-
-Every platform supports basic gestures like tap, swipe, and drag. Although the precise movements that make up basic gestures can vary per platform and input device, people are familiar with the underlying functionality of these gestures and expect to use them everywhere. For a list of these gestures, see [Standard gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures).
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/gestures#Best-practices)
-
-**Give people more than one way to interact with your app.** People commonly prefer or need to use other inputs — such as their voice, keyboard, or Switch Control — to interact with their devices. Don’t assume that people can use a specific gesture to perform a given task. For guidance, see [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility).
-
-**In general, respond to gestures in ways that are consistent with people’s expectations.** People expect most gestures to work the same regardless of their current context. For example, people expect tap to activate or select an object. Avoid using a familiar gesture like tap or swipe to perform an action that’s unique to your app; similarly, avoid creating a unique gesture to perform a standard action like activating a button or scrolling a long view.
-
-**Handle gestures as responsively as possible.** Useful gestures enhance the experience of direct manipulation and provide immediate feedback. As people perform a gesture in your app, provide feedback that helps them predict its results and, if necessary, communicates the extent and type of movement required to complete the action.
-
-**Indicate when a gesture isn’t available.** If you don’t clearly communicate why a gesture doesn’t work, people might think your app has frozen or they aren’t performing the gesture correctly, leading to frustration. For example, if someone tries to drag a locked object, the UI may not indicate that the object’s position has been locked; or if they try to activate an unavailable button, the button’s unavailable state may not be clearly distinct from its available state.
-
-## [Custom gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Custom-gestures)
-
-**Add custom gestures only when necessary.** Custom gestures work best when you design them for specialized tasks that people perform frequently and that aren’t covered by existing gestures, like in a game or drawing app. If you decide to implement a custom gesture, make sure it’s:
-
-  * Discoverable
-
-  * Straightforward to perform
-
-  * Distinct from other gestures
-
-  * Not the only way to perform an important action in your app or game
-
-
-
-
-**Make custom gestures easy to learn.** Offer moments in your app to help people quickly learn and perform custom gestures, and make sure to test your interactions in real use scenarios. If you’re finding it difficult to use simple language and graphics to describe a gesture, it may mean people will find the gesture difficult to learn and perform.
-
-**Use shortcut gestures to supplement standard gestures, not replace them.** While you may supply a custom gesture to quickly access parts of your app, people also need simple, familiar ways to navigate and perform actions, even if it means an extra tap or two. For example, in an app that supports navigation through a hierarchy of views, people expect to find a Back button in a top toolbar that lets them return to the previous view with a single tap. To help accelerate this action, many apps also offer a shortcut gesture — such as swiping from the side of a window or touchscreen — while continuing to provide the Back button.
-
-**Avoid conflicting with gestures that access system UI.** Several platforms offer gestures for accessing system behaviors, like edge swiping in watchOS or rolling your hand over to access system overlays in visionOS. It’s important to avoid defining custom gestures that might conflict with these interactions, as people expect these controls to work consistently. In specific circumstances within games or immersive experiences, developers can work around this area by deferring the system gesture. For more information, see the platform considerations for iOS, iPadOS, watchOS, and visionOS.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/gestures#Platform-considerations)
-
-### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/gestures#iOS-iPadOS)
-
-In addition to the [standard gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures) supported in all platforms, iOS and iPadOS support a few other gestures that people expect.
-
-Gesture| Common action  
----|---  
-Three-finger swipe| Initiate undo (left swipe); initiate redo (right swipe).  
-Three-finger pinch| Copy selected text (pinch in); paste copied text (pinch out).  
-Four-finger swipe (iPadOS only)| Switch between apps.  
-Shake| Initiate undo; initiate redo.  
-  
-**Consider allowing simultaneous recognition of multiple gestures if it enhances the experience.** Although simultaneous gestures are unlikely to be useful in nongame apps, a game might include multiple onscreen controls — such as a joystick and firing buttons — that people can operate at the same time. For guidance on integrating touchscreen input with Apple Pencil input in your iPadOS app, see [Apple Pencil and Scribble](https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble).
-
-### [macOS](https://developer.apple.com/design/human-interface-guidelines/gestures#macOS)
-
-People primarily interact with macOS using a [keyboard](https://developer.apple.com/design/human-interface-guidelines/keyboards) and mouse. In addition, they can make [standard gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures) on a Magic Trackpad, Magic Mouse, or a [game controller](https://developer.apple.com/design/human-interface-guidelines/game-controls) that includes a touch surface.
-
-### [tvOS](https://developer.apple.com/design/human-interface-guidelines/gestures#tvOS)
-
-People expect to use [standard gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures) to navigate tvOS apps and games with a compatible remote, Siri Remote, or [game controller](https://developer.apple.com/design/human-interface-guidelines/game-controls) that includes a touch surface. For guidance, see [Remotes](https://developer.apple.com/design/human-interface-guidelines/remotes).
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/gestures#visionOS)
-
-visionOS supports two categories of gestures: indirect and direct.
-
-People use an _indirect_ gesture by looking at an object to target it, and then manipulating that object from a distance — indirectly — with their hands. For example, a person can look at a button to focus it and select it by quickly tapping their finger and thumb together. Indirect gestures are comfortable to perform at any distance, and let people quickly change focus between different objects and select items with minimal movement.
-
-Video with custom controls. 
-
-Content description: A recording showing a closeup view of the top portion of a window in visionOS. A button in the window becomes highlighted. A picture-in-picture window is visible in the bottom-right corner of the recording. It shows a person's hand performing the indirect tap gesture. In response to the gesture, the highlighted button in the window activates. 
-
-Play 
-
-People use a _direct_ gesture to physically touch an interactive object. For example, people can directly type on the visionOS keyboard by tapping the virtual keys. Direct gestures work best when they are within reach. Because people may find it tiring to keep their arms raised for extended periods, direct gestures are best for infrequent use. visionOS also supports direct versions of all standard gestures, allowing people the choice to interact directly or indirectly with any standard component.
-
-Video with custom controls. 
-
-Content description: A recording showing a table with a vertical stack of three virtual cubic blocks on it in visionOS. A person moves their hand toward the blocks from right to left, and their extended fingers touch and push aside the center block. The center block falls to the side, and the other block also tumbles onto the tabletop. 
-
-Play 
-
-Here are the standard direct gestures people use in visionOS; see [Specifications](https://developer.apple.com/design/human-interface-guidelines/gestures#Specifications) for a list of standard indirect gestures.
-
-Direct gesture| Common use  
----|---  
-Touch| Directly select or activate an object.  
-Touch and hold| Open a contextual menu.  
-Touch and drag| Move an object to a new location.  
-Double touch| Preview an object or file; select a word in an editing context.  
-Swipe| Reveal actions and controls; dismiss views; scroll.  
-With two hands, pinch and drag together or apart| Zoom in or out.  
-With two hands, pinch and drag in a circular motion| Rotate an object.  
-  
-**Support standard gestures everywhere you can.** For example, as soon as someone looks at an object in your app or game, tap is the first gesture they’re likely to make when they want to select or activate it. Even if you also support custom gestures, supporting standard gestures such as tap helps people get comfortable with your app or game quickly.
-
-**Offer both indirect and direct interactions when possible.** Prefer indirect gestures for UI and common components like buttons. Reserve direct gestures and custom gestures for objects that invite close-up interaction or specific motions in a game or interactive experience.
-
-**Avoid requiring specific body movements or positions for input.** Not all people can perform specific body movements or position themselves in certain ways at all times, whether due to disability, spatial constraints, or other environmental factors. If your experience requires movement, consider supporting alternative inputs to let people choose the interaction method that works best for them.
-
-#### [Designing custom gestures in visionOS](https://developer.apple.com/design/human-interface-guidelines/gestures#Designing-custom-gestures-in-visionOS)
-
-If you want to offer a specific interaction for your experience that people can’t perform using an existing system gesture, consider designing a custom gesture. To offer this type of interaction, your app needs to be running in a Full Space, and you must request people’s permission to access information about their hands. For developer guidance, see [Setting up access to ARKit data](https://developer.apple.com/documentation/visionOS/setting-up-access-to-arkit-data).
-
-![A screenshot of a person's hands performing a custom gesture, placing the two hands together to form a heart, while playing a visionOS game.](https://docs-assets.developer.apple.com/published/363ecbc8eeb441809f62ae935e13fbdc/visionos-custom-spatial-gesture-happy-beam%402x.png)
-
-**Prioritize comfort.** Continually test ergonomics of all interactions that require custom gestures. A custom interaction that requires people to keep their arms raised for even a little while can be physically tiring, and repeating very similar movements many times in succession can stress people’s muscles and joints.
-
-**Carefully consider complex custom gestures that involve multiple fingers or both hands.** People may not always have both hands available when using your app or game. If you require a more complex gesture for your experience, consider also offering an alternative that requires less movement.
-
-**Avoid custom gestures that require using a specific hand.** It can increase someone’s cognitive load if they need to remember which hand to use to trigger a custom gesture. It may also make your experience less welcoming to people with strong hand-dominance or limb differences.
-
-#### [Working with system overlays in visionOS](https://developer.apple.com/design/human-interface-guidelines/gestures#Working-with-system-overlays-in-visionOS)
-
-In visionOS 2 and later, people can look at the palm of one hand and use gestures to quickly access system overlays for Home and Control Center. These interactions are available systemwide, and are reserved solely for accessing system overlays.
-
-Note
-
-The system overlay is the default method of accessing Control Center in visionOS 2 and later. The visionOS 1 behavior (looking upward) remains available as an accessibility setting.
-
-When designing apps and games that use custom gestures or anchor content to a person’s hands, it’s important to take interactions with the system overlays into consideration.
-
-**Reserve the area around a person’s hand for system overlays and their related gestures.** If possible, don’t anchor content to a person’s hands or wrists. If you’re designing a game that involves hand-anchored content, place it outside of the immediate area of someone’s hand to avoid colliding with the Home indicator.
-
-![An illustration of a person's open hand with the palm facing upward. A dashed circular line above the hand indicates the area reserved for system overlays.](https://docs-assets.developer.apple.com/published/de8c04a523a3e225c723c5c09c458e1c/visionos-hand-area-of-focus%402x.png)The area reserved for interacting with system overlays.
-
-![An illustration of a person's open hand with the palm facing upward. A button with a circle icon representing the Home indicator appears above the palm.](https://docs-assets.developer.apple.com/published/961d33f07da24b20848f3502d2cea134/visionos-spatial-gesture-home-indicator%402x.png)A person looks at their palm to reveal the Home indicator.
-
-![An illustration of a person's open hand with the palm facing downward. An overlay with the status bar appears above the hand.](https://docs-assets.developer.apple.com/published/f1d5a8816f65f35853ccd513355272d8/visionos-spatial-gesture-control-center%402x.png)A person turns their hand to reveal the status bar, and can tap to open Control Center.
-
-**Consider deferring the system overlay behavior when designing an immersive app or game.** In certain circumstances, you may not want the Home indicator to appear when someone looks at the palm of their hand. For example, a game that uses virtual hands or gloves may want to keep someone within the world of the story, even if they happen to look at their hands from different angles. In such cases, when your app is running in a Full Space, you can choose to require a tap to reveal the Home indicator instead. For developer guidance, see [`persistentSystemOverlays(_:)`](https://developer.apple.com/documentation/SwiftUI/View/persistentSystemOverlays\(_:\)).
-
-![An image of a person's open hand with the palm facing upward, shown from the person's perspective. A button with a circle icon representing the Home indicator appears above the palm. The image background shows the room that's the person's surroundings.](https://docs-assets.developer.apple.com/published/dc6b4a94633c063ddd432dcc8043cae3/gestures-default-home-indicator%402x.png)Default behavior in the Shared Space
-
-![An image of a person's open hand with the palm facing upward, shown from the person's perspective. A button with a circle icon representing the Home indicator appears above the palm. The image background shows a forest in a fully immersive space.](https://docs-assets.developer.apple.com/published/96cb708d391f1ab78a77d23c7f2e0442/gestures-home-indicator-in-immersive-space%402x.png)Default behavior in a Full Space
-
-![An image of a person's open hand wearing a bulky space suit glove, shown from the person's perspective. The palm faces upward, and no button appears above it. The image background shows a starry sky in a fully immersive space.](https://docs-assets.developer.apple.com/published/b978fe99b00df892890e1d194f704a83/gestures-fully-immersive-game-with-glove%402x.png)Deferred behavior in a Full Space
-
-Note
-
-Apps and games that you built for visionOS 1 defer the system overlay behavior by default. When a person looks at their palm with your app running in a Full Space, the Home indicator won’t appear unless they tap first.
-
-**Use caution when designing custom gestures that involve a rolling motion of the hand, wrist, and forearm.** This specific motion is reserved for revealing system overlays. Since system overlays always display on top of app content and your app isn’t aware of when they’re visible, it’s important to test any custom gestures or content that might conflict.
-
-### [watchOS](https://developer.apple.com/design/human-interface-guidelines/gestures#watchOS)
-
-#### [Double tap](https://developer.apple.com/design/human-interface-guidelines/gestures#Double-tap)
-
-In watchOS 11 and later, people can use the double-tap gesture to scroll through lists and scroll views, and to advance between vertical tab views. Additionally, you can specify a toggle or button as the primary action in your app, or in your widget or Live Activity when the system displays it in the Smart Stack. Double-tapping in a view with a primary action highlights the control and then performs the action. The system also supports double tap for custom actions that you offer in [notifications](https://developer.apple.com/design/human-interface-guidelines/notifications), where it acts on the first nondestructive action in the notification.
-
-**Avoid setting a primary action in views with lists, scroll views, or vertical tabs.** This conflicts with the default navigation behaviors that people expect when they double-tap.
-
-**Choose the button that people use most commonly as the primary action in a view.** Double tap is helpful in a nonscrolling view when it performs the action that people use the most. For example, in a media controls view, you could assign the primary action to the play/pause button. For developer guidance, see [`handGestureShortcut(_:isEnabled:)`](https://developer.apple.com/documentation/SwiftUI/View/handGestureShortcut\(_:isEnabled:\)) and [`primaryAction`](https://developer.apple.com/documentation/SwiftUI/HandGestureShortcut/primaryAction).
-
-## [Specifications](https://developer.apple.com/design/human-interface-guidelines/gestures#Specifications)
-
-### [Standard gestures](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures)
-
-The system provides APIs that support the familiar gestures people use with their devices, whether they use a touchscreen, an indirect gesture in visionOS, or an input device like a trackpad, mouse, remote, or game controller. For developer guidance, see [Gestures](https://developer.apple.com/documentation/SwiftUI/Gestures).
-
-Gesture| Supported in| Common action  
----|---|---  
-Tap| iOS, iPadOS, macOS, tvOS, visionOS, watchOS| Activate a control; select an item.  
-Swipe| iOS, iPadOS, macOS, tvOS, visionOS, watchOS| Reveal actions and controls; dismiss views; scroll.  
-Drag| iOS, iPadOS, macOS, tvOS, visionOS, watchOS| Move a UI element.  
-Touch (or pinch) and hold| iOS, iPadOS, tvOS, visionOS, watchOS| Reveal additional controls or functionality.  
-Double tap| iOS, iPadOS, macOS, tvOS, visionOS, watchOS| Zoom in; zoom out if already zoomed in; perform a primary action on Apple Watch Series 9 and Apple Watch Ultra 2.  
-Zoom| iOS, iPadOS, macOS, tvOS, visionOS| Zoom a view; magnify content.  
-Rotate| iOS, iPadOS, macOS, tvOS, visionOS| Rotate a selected item.  
-  
-For guidance on supporting additional gestures and button presses on specific input devices, see [Pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices), [Remotes](https://developer.apple.com/design/human-interface-guidelines/remotes), and [Game controls](https://developer.apple.com/design/human-interface-guidelines/game-controls).
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/gestures#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/gestures#Related)
-
-[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
-
-[Eyes](https://developer.apple.com/design/human-interface-guidelines/eyes)
-
-[Playing haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/gestures#Developer-documentation)
-
-[Gestures](https://developer.apple.com/documentation/SwiftUI/Gestures) — SwiftUI
-
-[`UITouch`](https://developer.apple.com/documentation/UIKit/UITouch) — UIKit
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/gestures#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/C03E6E6D-A32A-41D0-9E50-C3C6059820AA/B38CC217-7635-48EF-B8C9-F7954F390CCE/9273_wide_250x141_1x.jpg) Enhance your UI animations and transitions ](https://developer.apple.com/videos/play/wwdc2024/10145)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/C6CDCC79-CCD0-4D2F-A4D1-8FC70DC663DB/8127_wide_250x141_1x.jpg) Design for spatial input ](https://developer.apple.com/videos/play/wwdc2023/10073)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/gestures#Change-log)
-
-Date| Changes  
----|---  
-September 9, 2024| Added guidance for working with system overlays in visionOS and made organizational updates.  
-September 15, 2023| Updated specifications to include double tap in watchOS.  
-June 21, 2023| Changed page title from Touchscreen gestures and updated to include guidance for visionOS.  
-  

package/templates/vault/hig-inputs/references/gyro-and-accelerometer.md

@@ -1,40 +0,0 @@
----
-title: "Gyroscope and accelerometer | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer
-
-# Gyroscope and accelerometer
-
-On-device gyroscopes and accelerometers can supply data about a device’s movement in the physical world.
-
-![A sketch of a gyroscope, suggesting movement. The image is overlaid with rectangular and circular grid lines and is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/d095e989767ecf0537fa99b6ea46b50a/inputs-gyroscope-intro%402x.png)
-
-You can use accelerometer and gyroscope data to provide experiences based on real-time, motion-based information in apps and games that run in iOS, iPadOS, and watchOS. tvOS apps can use gyroscope data from the Siri Remote. For developer guidance, see [Core Motion](https://developer.apple.com/documentation/CoreMotion).
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Best-practices)
-
-**Use motion data only to offer a tangible benefit to people.** For example, a fitness app might use the data to provide feedback about people’s activity and general health, and a game might use the data to enhance gameplay. Avoid gathering data simply to have the data.
-
-Important
-
-If your experience needs to access motion data from a device, you must provide copy that explains why. The first time your app or game tries to access this type of data, the system includes your copy in a permission request, where people can grant or deny access.
-
-**Outside of active gameplay, avoid using accelerometers or gyroscopes for the direct manipulation of your interface.** Some motion-based gestures may be difficult to replicate precisely, may be physically challenging for some people to perform, and may affect battery usage.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Platform-considerations)
-
- _No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS._
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Related)
-
-[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Developer-documentation)
-
-[Getting processed device-motion data](https://developer.apple.com/documentation/CoreMotion/getting-processed-device-motion-data) — Core Motion
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/119/5077B5B0-643B-4E31-9C5E-6E766326D3F3/5225_wide_250x141_1x.jpg) Measure health with motion ](https://developer.apple.com/videos/play/wwdc2021/10287)
-

package/templates/vault/hig-inputs/references/keyboards.md

@@ -1,234 +0,0 @@
----
-title: "Keyboards | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/keyboards
-
-# Keyboards
-
-A physical keyboard can be an essential input device for entering text, playing games, controlling apps, and more.
-
-![A sketch of a keyboard, suggesting keyboard input. The image is overlaid with rectangular and circular grid lines and is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/041dcf36a378d11a3727a6ff04989365/inputs-keyboard-intro%402x.png)
-
-People can connect a physical keyboard to any device except Apple Watch. Mac users tend to use a physical keyboard all the time and iPad users often do. Many games work well with a physical keyboard, and people can prefer using one instead of a [virtual keyboard](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards) when entering a lot of text.
-
-Keyboard users often appreciate using keyboard shortcuts to speed up their interactions with apps and games. A _keyboard shortcut_ is a combination of a primary key and one or more modifier keys (Control, Option, Shift, and Command) that map to a specific command. A keyboard shortcut in a game — called a _key binding_ — often consists of a single key.
-
-Apple defines standard keyboard shortcuts to work consistently across the system and most apps, helping people transfer their knowledge to new experiences. Some apps define custom keyboard shortcuts for the app-specific commands people use most; most games define custom key bindings that make it quick and efficient to use the keyboard to control the game. For guidance, see [Game controls](https://developer.apple.com/design/human-interface-guidelines/game-controls#Keyboards).
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/keyboards#Best-practices)
-
-**Support Full Keyboard Access when possible.** Available in iOS, iPadOS, macOS, and visionOS, Full Keyboard Access lets people navigate and activate windows, menus, controls, and system features using only the keyboard. To test Full Keyboard Access in your app or game, turn it on in the Accessibility area of the system-supplied Settings app. For developer guidance, see [Support Full Keyboard Access in your iOS app](https://developer.apple.com/videos/play/wwdc2021/10120/) and [`isFullKeyboardAccessEnabled`](https://developer.apple.com/documentation/AppKit/NSApplication/isFullKeyboardAccessEnabled).
-
-Important
-
-Although iPadOS supports keyboard navigation in text fields, text views, and sidebars, and provides APIs you can use to support it in collection views and other custom views, avoid supporting keyboard navigation for controls, such as buttons, segmented controls, and switches. Instead, let people use Full Keyboard Access to activate controls, navigate to all onscreen components, and perform gesture-based interactions like drag and drop. For guidance, see [iPadOS](https://developer.apple.com/design/human-interface-guidelines/focus-and-selection#iPadOS); for developer guidance, see [Focus-based navigation](https://developer.apple.com/documentation/uikit/focus-based_navigation).
-
-**Respect standard keyboard shortcuts.** While using most apps, people generally expect to rely on the standard keyboard shortcuts that work in other apps and throughout the system. If your app offers a unique action that people perform frequently, prefer creating a [custom](https://developer.apple.com/design/human-interface-guidelines/keyboards#Custom-keyboard-shortcuts) shortcut for it instead of repurposing a standard one that people associate with a different action. While playing a game, people may expect to use certain standard keyboard shortcuts — such as Command–Q to quit the game — but they also expect to be able to modify each game’s key bindings to fit their personal play style. For guidance, see [Game controls](https://developer.apple.com/design/human-interface-guidelines/game-controls#Keyboards).
-
-## [Standard keyboard shortcuts](https://developer.apple.com/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts)
-
-**In general, don’t repurpose standard keyboard shortcuts for custom actions.** People can get confused when the shortcuts they know work differently in your app or game. Only consider redefining a standard shortcut if its action doesn’t make sense in your experience. For example, if your app doesn’t support text editing, it doesn’t need a text-styling command like Italic, so you might repurpose Command–I for an action that has more relevance, like Get Info.
-
-People expect each of the following standard keyboard shortcuts to perform the action listed in the table below.
-
-Primary key| Keyboard shortcut| Action  
----|---|---  
-Space| Command-Space| Show or hide the Spotlight search field.  
-| Shift-Command-Space| Varies.  
-| Option-Command-Space| Show the Spotlight search results window.  
-| Control-Command-Space| Show the Special Characters window.  
-Tab| Shift-Tab| Navigate through controls in a reverse direction.  
-| Command-Tab| Move forward to the next most recently used app in a list of open apps.  
-| Shift-Command-Tab| Move backward through a list of open apps (sorted by recent use).  
-| Control-Tab| Move focus to the next group of controls in a dialog or the next table (when Tab moves to the next cell).  
-| Control-Shift-Tab| Move focus to the previous group of controls.  
-Esc| Esc| Cancel the current action or process.  
-Esc| Option-Command-Esc| Open the Force Quit dialog.  
-Eject| Control-Command-Eject| Quit all apps (after changes have been saved to open documents) and restart the computer.  
-| Control-Option-Command-Eject| Quit all apps (after changes have been saved to open documents) and shut the computer down.  
-F1| Control-F1| Toggle full keyboard access on or off.  
-F2| Control-F2| Move focus to the menu bar.  
-F3| Control- F3| Move focus to the Dock.  
-F4| Control-F4| Move focus to the active (or next) window.  
-| Control-Shift-F4| Move focus to the previously active window.  
-F5| Control-F5| Move focus to the toolbar.  
-| Command-F5| Turn VoiceOver on or off.  
-F6| Control-F6| Move focus to the first (or next) panel.  
-| Control-Shift-F6| Move focus to the previous panel.  
-F7| Control-F7| Temporarily override the current keyboard access mode in windows and dialogs.  
-F8| | Varies.  
-F9| | Varies.  
-F10| | Varies.  
-F11| | Show desktop.  
-F12| | Hide or display Dashboard.  
-Grave accent (`)| Command-Grave accent| Activate the next open window in the frontmost app.  
-| Shift-Command-Grave accent| Activate the previous open window in the frontmost app.  
-| Option-Command-Grave accent| Move focus to the window drawer.  
-Hyphen (-)| Command-Hyphen| Decrease the size of the selection.  
-| Option-Command-Hyphen| Zoom out when screen zooming is on.  
-Left bracket ({)| Command-Left bracket| Left-align a selection.  
-Right bracket (})| Command-Right bracket| Right-align a selection.  
-Pipe (|)| Command-Pipe| Center-align a selection.  
-Colon (:)| Command-Colon| Display the Spelling window.  
-Semicolon (;)| Command-Semicolon| Find misspelled words in the document.  
-Comma (,)| Command-Comma| Open the app’s settings window.  
-| Control-Option-Command-Comma| Decrease screen contrast.  
-Period (.)| Command-Period| Cancel an operation.  
-| Control-Option-Command-Period| Increase screen contrast.  
-Question mark (?)| Command-Question mark| Open the app’s Help menu.  
-Forward slash (/)| Option-Command-Forward slash| Turn font smoothing on or off.  
-Equal sign (=)| Shift-Command-Equal sign| Increase the size of the selection.  
-| Option-Command-Equal sign| Zoom in when screen zooming is on.  
-3| Shift-Command-3| Capture the screen to a file.  
-| Control-Shift-Command-3| Capture the screen to the Clipboard.  
-4| Shift-Command-4| Capture a selection to a file.  
-| Control-Shift-Command-4| Capture a selection to the Clipboard.  
-8| Option-Command-8| Turn screen zooming on or off.  
-| Control-Option-Command-8| Invert the screen colors.  
-A| Command-A| Select every item in a document or window, or all characters in a text field.  
-| Shift-Command-A| Deselect all selections or characters.  
-B| Command-B| Boldface the selected text or toggle boldfaced text on and off.  
-C| Command-C| Copy the selection to the Clipboard.  
-| Shift-Command-C| Display the Colors window.  
-| Option-Command-C| Copy the style of the selected text.  
-| Control-Command-C| Copy the formatting settings of the selection and store on the Clipboard.  
-D| Option-Command-D| Show or hide the Dock.  
-| Control-Command-D| Display the definition of the selected word in the Dictionary app.  
-E| Command-E| Use the selection for a find operation.  
-F| Command-F| Open a Find window.  
-| Option-Command-F| Jump to the search field control.  
-| Control-Command-F| Enter full screen.  
-G| Command-G| Find the next occurrence of the selection.  
-| Shift-Command-G| Find the previous occurrence of the selection.  
-H| Command-H| Hide the windows of the currently running app.  
-| Option-Command-H| Hide the windows of all other running apps.  
-I| Command-I| Italicize the selected text or toggle italic text on or off.  
-| Command-I| Display an Info window.  
-| Option-Command-I| Display an inspector window.  
-J| Command-J| Scroll to a selection.  
-M| Command-M| Minimize the active window to the Dock.  
-| Option-Command-M| Minimize all windows of the active app to the Dock.  
-N| Command-N| Open a new document.  
-O| Command-O| Display a dialog for choosing a document to open.  
-P| Command-P| Display the Print dialog.  
-| Shift-Command-P| Display the Page Setup dialog.  
-Q| Command-Q| Quit the app.  
-| Shift-Command-Q| Log out the person currently logged in.  
-| Option-Shift-Command-Q| Log out the person currently logged in without confirmation.  
-S| Command-S| Save a new document or save a version of a document.  
-| Shift-Command-S| Duplicate the active document or initiate a Save As.  
-T| Command-T| Display the Fonts window.  
-| Option-Command-T| Show or hide a toolbar.  
-U| Command-U| Underline the selected text or turn underlining on or off.  
-V| Command-V| Paste the Clipboard contents at the insertion point.  
-| Shift-Command-V| Paste as (Paste as Quotation, for example).  
-| Option-Command-V| Apply the style of one object to the selection.  
-| Option-Shift-Command-V| Paste the Clipboard contents at the insertion point and apply the style of the surrounding text to the inserted object.  
-| Control-Command-V| Apply formatting settings to the selection.  
-W| Command-W| Close the active window.  
-| Shift-Command-W| Close a file and its associated windows.  
-| Option-Command-W| Close all windows in the app.  
-X| Command-X| Remove the selection and store on the Clipboard.  
-Z| Command-Z| Undo the previous operation.  
-| Shift-Command-Z| Redo (when Undo and Redo are separate commands rather than toggled using Command-Z).  
-Right arrow| Command-Right arrow| Change the keyboard layout to current layout of Roman script.  
-| Shift-Command-Right arrow| Extend selection to the next semantic unit, typically the end of the current line.  
-| Shift-Right arrow| Extend selection one character to the right.  
-| Option-Shift-Right arrow| Extend selection to the end of the current word, then to the end of the next word.  
-| Control-Right arrow| Move focus to another value or cell within a view, such as a table.  
-Left arrow| Command-Left arrow| Change the keyboard layout to current layout of system script.  
-| Shift-Command-Left arrow| Extend selection to the previous semantic unit, typically the beginning of the current line.  
-| Shift-Left arrow| Extend selection one character to the left.  
-| Option-Shift-Left arrow| Extend selection to the beginning of the current word, then to the beginning of the previous word.  
-| Control-Left arrow| Move focus to another value or cell within a view, such as a table.  
-Up arrow| Shift-Command-Up arrow| Extend selection upward in the next semantic unit, typically the beginning of the document.  
-| Shift-Up arrow| Extend selection to the line above, to the nearest character boundary at the same horizontal location.  
-| Option-Shift-Up arrow| Extend selection to the beginning of the current paragraph, then to the beginning of the next paragraph.  
-| Control-Up arrow| Move focus to another value or cell within a view, such as a table.  
-Down arrow| Shift-Command-Down arrow| Extend selection downward in the next semantic unit, typically the end of the document.  
-| Shift-Down arrow| Extend selection to the line below, to the nearest character boundary at the same horizontal location.  
-| Option-Shift-Down arrow| Extend selection to the end of the current paragraph, then to the end of the next paragraph (include the paragraph terminator, such as Return, in cut, copy, and paste operations).  
-| Control-Down arrow| Move focus to another value or cell within a view, such as a table.  
-  
-The system also defines several keyboard shortcuts for use with localized versions of the system, localized keyboards, keyboard layouts, and input methods. These shortcuts don’t correspond directly to menu commands.
-
-Keyboard shortcut| Action  
----|---  
-Control-Space| Toggle between the current and last input source.  
-Control-Option-Space| Switch to the next input source in the list.  
-[Modifier key]-Command-Space| Varies.  
-Command-Right arrow| Change keyboard layout to current layout of Roman script.  
-Command-Left arrow| Change keyboard layout to current layout of system script.  
-  
-## [Custom keyboard shortcuts](https://developer.apple.com/design/human-interface-guidelines/keyboards#Custom-keyboard-shortcuts)
-
-**Define custom keyboard shortcuts for only the most frequently used app-specific commands.** People appreciate using keyboard shortcuts for actions they perform frequently, but defining too many new shortcuts can make your app seem difficult to learn.
-
-**Use modifier keys in ways that people expect.** For example, pressing Command while dragging moves items as a group, and pressing Shift while drag-resizing constrains resizing to the item’s aspect ratio. In addition, holding an arrow key moves the selected item by the smallest app-defined unit of distance until people release the key.
-
-Here are the modifier keys and the symbols that represent them.
-
-Modifier key| Symbol| Recommended usage  
----|---|---  
-Command| ![Outline of a stylized clover shape.](https://docs-assets.developer.apple.com/published/43dd468e7f303fbaa3abbf3935292ae2/Keyboard_Command.svg)| Prefer the Command key as the main modifier key in a custom keyboard shortcut.  
-Shift| ![Outline of an upward-pointing arrow.](https://docs-assets.developer.apple.com/published/3a7e5aed7275031a8c41a7fb7789e41f/Keyboard_Shift.svg)| Prefer the Shift key as a secondary modifier that complements a related shortcut.  
-Option| ![Line segments that suggest a horizontally transformed Z shape combined with a short horizontal segment aligned with the top of the Z.](https://docs-assets.developer.apple.com/published/8b064ad029d2012128a6aaeb1322b290/Keyboard_Option.svg)| Use the Option modifier sparingly for less-common commands or power features.  
-Control| ![A shallow, upside-down V shape.](https://docs-assets.developer.apple.com/published/5c92c8350588d52ff786bf763b18e9e7/Keyboard_Control.svg)| Avoid using the Control key as a modifier. The system uses Control in many systemwide features and shortcuts, like moving focus or capturing screenshots.  
-  
-Tip
-
-Some languages require modifier keys to generate certain characters. For example, on a French keyboard, Option-5 generates the “{“ character. It’s usually safe to use the Command key as a modifier, but avoid using an additional modifier with characters that aren’t available on all keyboards. If you must use a modifier other than Command, prefer using it only with the alphabetic characters.
-
-**List modifier keys in the correct order.** If you use more than one modifier key in a custom shortcut, always list them in this order: Control, Option, Shift, Command.
-
-**Avoid adding Shift to a shortcut that uses the upper character of a two-character key.** People already understand that they must hold the Shift key to type the upper character of a two-character key, so it’s clearer to simply list the upper character in the shortcut. For example, the keyboard shortcut for Hide Status Bar is Command-Slash, whereas the keyboard shortcut for Help is Command-Question mark, not Shift-Command-Slash.
-
-**Let the system localize and mirror your keyboard shortcuts as needed.** The system automatically localizes a shortcut’s primary and modifier keys to support the currently connected keyboard; if your app or game switches to a right-to-left layout, the system automatically mirrors the shortcut. For guidance, see [Right to left](https://developer.apple.com/design/human-interface-guidelines/right-to-left).
-
-**Avoid creating a new shortcut by adding a modifier to an existing shortcut for an unrelated command.** For example, because people are accustomed to using Command-Z for undoing an action, it would be confusing to use Shift-Command-Z as the shortcut for a command that’s unrelated to undo and redo.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/keyboards#Platform-considerations)
-
- _No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS._
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/keyboards#visionOS)
-
-In visionOS, an app’s keyboard shortcuts appear in the shortcut interface that displays when people hold the Command key on a connected keyboard. Similar in organization to an app’s [menu bar menus](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar) on iPad or Mac, the shortcut interface on Apple Vision Pro displays app commands in familiar system-defined menu categories such as File, Edit, and View. Unlike menu bar menus, the shortcut interface displays all relevant categories in one view, listing within each category only available commands that also have shortcuts.
-
-**Write descriptive shortcut titles.** Because the shortcut interface displays a flat list of all items in each category, submenu titles aren’t available to provide context for their child items. Make sure each shortcut title is descriptive enough to convey its action without the additional context a submenu title might provide. For developer guidance, see [`discoverabilityTitle`](https://developer.apple.com/documentation/UIKit/UIKeyCommand/discoverabilityTitle).
-
-**Recognize that people see an overlay when they use a physical keyboard with your visionOS app or game.** When people connect a physical keyboard while using your visionOS app or game, the system displays a virtual keyboard overlay that provides typing completion and other controls.
-
-Video with custom controls. 
-
-Content description: A recording that shows two hands typing on a physical keyboard while the person runs an app in visionOS. A virtual window is visible above the physical keyboard, and displays the entered text and suggestions. 
-
-Play 
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/keyboards#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/keyboards#Related)
-
-[Virtual keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards)
-
-[Entering data](https://developer.apple.com/design/human-interface-guidelines/entering-data)
-
-[Pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/keyboards#Developer-documentation)
-
-[`KeyboardShortcut`](https://developer.apple.com/documentation/SwiftUI/KeyboardShortcut) — SwiftUI
-
-[Input events](https://developer.apple.com/documentation/SwiftUI/Input-events) — SwiftUI
-
-[Handling key presses made on a physical keyboard](https://developer.apple.com/documentation/UIKit/handling-key-presses-made-on-a-physical-keyboard) — UIKit
-
-[Mouse, Keyboard, and Trackpad](https://developer.apple.com/documentation/AppKit/mouse-keyboard-and-trackpad) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/keyboards#Change-log)
-
-Date| Changes  
----|---  
-June 9, 2025| Moved game-specific key bindings guidance to the Game controls page.  
-June 10, 2024| Added game-specific guidance and made organizational updates.  
-June 21, 2023| Updated to include guidance for visionOS.  
-  

package/templates/vault/hig-inputs/references/nearby-interactions.md

@@ -1,70 +0,0 @@
----
-title: "Nearby interactions | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/nearby-interactions
-
-# Nearby interactions
-
-Nearby interactions support on-device experiences that integrate the presence of people and objects in the nearby environment.
-
-![A sketch of curved lines beside a circular area containing a smaller circle, suggesting audio approaching a person in a room from a specific direction. The image is overlaid with rectangular and circular grid lines and is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/4ee9418314d3a8bbdc8e7586a9e3c787/inputs-nearby-interactions-intro%402x.png)
-
-A great nearby interaction feels intuitive and natural to people, because it builds on their innate awareness of the world around them. For example, a person playing music on their iPhone can continue listening on their HomePod mini when they bring the devices close together, simply by transferring the audio output from their iPhone to the HomePod mini.
-
-Nearby interactions are available on devices that support Ultra Wideband technology (to learn more, see [Ultra Wideband availability](https://support.apple.com/en-us/HT212274)), and rely on the [Nearby Interaction](https://developer.apple.com/documentation/NearbyInteraction) framework. Before participating in nearby interaction experiences, people grant permission for their device to interact while they’re using your app. The Nearby Interaction APIs help you preserve people’s privacy by relying on randomly generated device identifiers that last only as long as the interaction session your app initiates.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Best-practices)
-
-**Consider a task from the perspective of the physical world to find inspiration for a nearby interaction.** For example, although people can easily use your app’s UI to transfer a song from their iPhone to their HomePod mini, initiating the transfer by bringing the devices close together makes the task feel rooted in the physical world. Discovering the physical actions that inform the concept of a task can help you create an engaging experience that makes performing it feel easy and natural.
-
-**Use distance, direction, and context to inform an interaction.** Although your app may get information from a variety of sources, prioritizing nearby, contextually relevant information can help you deliver experiences that feel organic. For example, if people want to share content with a friend in a crowded room, the iOS share sheet can suggest a likely recipient by using on-device knowledge about the person’s most frequent and recent contacts. Combining this knowledge with information from nearby devices that include the U1 chip can let the share sheet improve the experience by suggesting the closest contact the person is facing.
-
-**Consider how changes in physical distance can guide a nearby interaction.** In the physical world, people generally expect their perception of an object to sharpen as they get closer to it. A nearby interaction can mirror this experience by providing feedback that changes with the proximity of an object. For example, when people use iPhone to find an AirTag, the display transitions from a directional arrow to a pulsing circle as they get closer.
-
-**Provide continuous feedback.** Continuous feedback reflects the dynamism of the physical world and strengthens the connection between a nearby interaction and the task people are performing. For example, when looking for a lost item in Find My, people get continuous updates that communicate the item’s direction and proximity. Keep people engaged by providing uninterrupted feedback that responds to their movements.
-
-**Consider using multiple feedback types to create a holistic experience.** Fluidly transitioning among visual, audible, and haptic feedback can help a nearby interaction’s task feel more engaging and real. Using more than one type of feedback also lets you vary the experience to coordinate with both the task and the current context. For example, while people are interacting with the device screen, visual feedback makes sense; while people are interacting with their environment, audible and haptic feedback often work better.
-
-**Avoid using a nearby interaction as the only way to perform a task.** You can’t assume that everyone can experience a nearby interaction, so it’s essential to provide alternative ways to get things done in your app.
-
-## [Device usage](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Device-usage)
-
-**Encourage people to hold the device in portrait orientation.** Holding a device in landscape can decrease the accuracy and availability of information about the distance and relative direction of other devices. If you support only portrait orientation while your nearby interaction feature runs, prefer giving people implicit, visual feedback on how to hold the device for an optimal experience; when possible, avoid explicitly telling people to hold the device in portrait.
-
-**Design for the device’s directional field of view.** Nearby interaction relies on a hardware sensor with a specific field of view similar to that of the Ultra Wide camera in iPhone 11 and later. If a participating device is outside of this field of view, your app might receive information about its distance, but not its relative direction.
-
-**Help people understand how intervening objects can affect the nearby interaction experience in your app.** When other people, animals, or sufficiently large objects come between two participating devices, the accuracy or availability of distance and direction information can decrease. Consider adding advice on avoiding this situation to onboarding or tutorial content you present.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Platform-considerations)
-
- _No additional considerations for iPadOS. Not supported in macOS, tvOS, or visionOS._
-
-### [iOS](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#iOS)
-
-On iPhone, Nearby Interaction APIs provide a peer device’s distance and direction.
-
-### [watchOS](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#watchOS)
-
-On Apple Watch, Nearby Interaction APIs provide a peer device’s distance. Also, all watchOS apps participating in a nearby interaction experience must be in the foreground.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Related)
-
-[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Developer-documentation)
-
-[Nearby Interaction](https://developer.apple.com/documentation/NearbyInteraction)
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/119/0F487599-C14E-48B0-AEB0-A752DFF26E95/5165_wide_250x141_1x.jpg) Design for spatial interaction ](https://developer.apple.com/videos/play/wwdc2021/10245)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/49/E6812719-14BF-4392-84FC-E1CFC1650B71/3558_wide_250x141_1x.jpg) Meet Nearby Interaction ](https://developer.apple.com/videos/play/wwdc2020/10668)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/nearby-interactions#Change-log)
-
-Date| Changes  
----|---  
-June 21, 2023| Changed page title from Spatial interactions.  
-