@ngxtm/devkit 3.15.0 → 3.16.0

package/skills/hig-patterns/references/collaboration-and-sharing.md

@@ -0,0 +1,86 @@
+---
+title: "Collaboration and sharing | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing
+
+# Collaboration and sharing
+
+Great collaboration and sharing experiences are simple and responsive, letting people engage with the content while communicating effectively with others.
+
+![A sketch of a person with an overlapping checkmark, suggesting effective collaboration. 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/ff23fbfe77df77f6bd5dd710a474b15b/patterns-collaboration-and-sharing-intro%402x.png)
+
+System interfaces and the Messages app can help you provide consistent and convenient ways for people to collaborate and share. For example, people can share content or begin a collaboration by dropping a document into a Messages conversation or selecting a destination in the familiar share sheet.
+
+After a collaboration begins, people can use the Collaboration button in your app to communicate with others, perform custom actions, and manage details. In addition, people can receive Messages notifications when collaborators mention them, make changes, join, or leave.
+
+You can take advantage of Messages integration and the system-provided sharing interfaces whether you implement collaboration and sharing through CloudKit, iCloud Drive, or a custom solution. To offer these features when you use a custom collaboration infrastructure, make sure your app also supports universal links (for developer guidance, see [Supporting universal links in your app](https://developer.apple.com/documentation/Xcode/supporting-universal-links-in-your-app)).
+
+In addition to helping people share and collaborate on documents, visionOS supports immersive sharing experiences through SharePlay. For guidance, see [SharePlay](https://developer.apple.com/design/human-interface-guidelines/shareplay).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Best-practices)
+
+**Place the Share button in a convenient location, like a toolbar, to make it easy for people to start sharing or collaborating.** In iOS 16, the system-provided share sheet includes ways to choose a file-sharing method and set permissions for a new collaboration; iPadOS 16 and macOS 13 introduce similar appearance and functionality in the sharing popover. In your SwiftUI app, you can also enable sharing by presenting a share link that opens the system-provided share sheet when people choose it; for developer guidance, see [`ShareLink`](https://developer.apple.com/documentation/SwiftUI/ShareLink).
+
+![An illustration of a Notes document on iPhone. The document toolbar prominently features the Share button next to the More button.](https://docs-assets.developer.apple.com/published/00e4629ef73463727909ceecefdf902f/collaboration-share-button%402x.png)
+
+**If necessary, customize the share sheet or sharing popover to offer the types of file sharing your app supports.** If you use CloudKit, you can add support for sending a copy of a file by passing both the file and your collaboration object to the share sheet. Because the share sheet has built-in support for multiple items, it automatically detects the file and makes the “send copy” functionality available. With iCloud Drive, your collaboration object supports “send copy” functionality by default. For custom collaboration, you can support “send copy” functionality in the share sheet by including a file — or a plain text representation of it — in your collaboration object.
+
+**Write succinct phrases that summarize the sharing permissions you support.** For example, you might write phrases like “Only invited people can edit” or “Everyone can make changes.” The system uses your permission summary in a button that reveals a set of sharing options that people use to define the collaboration.
+
+![An illustration of a Notes document with the share sheet open on iPhone, with collaboration options set to indicate that only invited people can edit the selected document.](https://docs-assets.developer.apple.com/published/b30d247d67d1ba3841be8414b65b7320/collaboration-sharing-permission-invited%402x.png)
+
+![An illustration of a Notes document with the share sheet open on iPhone, with collaboration options set to indicate that everyone can make changes to the selected document.](https://docs-assets.developer.apple.com/published/2bb4701135ff5cf50b67122ea93ea1ef/collaboration-sharing-permission-everyone%402x.png)
+
+**Provide a set of simple sharing options that streamline collaboration setup.** You can customize the view that appears when people choose the permission summary button to provide choices that reflect your collaboration functionality. For example, you might offer options that let people specify who can access the content and whether they can edit it or just read it, and whether collaborators can add new participants. Keep the number of custom choices to a minimum and group them in ways that help people understand them at a glance.
+
+**Prominently display the Collaboration button as soon as collaboration starts.** The system-provided Collaboration button reminds people that the content is shared and identifies who’s sharing it. Because the Collaboration button typically appears after people interact with the share sheet or sharing popover, it works well to place it next to the Share button.
+
+![An illustration of a Notes document open on iPhone. The document toolbar prominently features the Collaboration button next to the Share button.](https://docs-assets.developer.apple.com/published/22a789e7f8d5b3b6a22b3763b21288bd/collaboration-status-active-collaboration-button%402x.png)
+
+**Provide custom actions in the collaboration popover only if needed.** Choosing the Collaboration button in your app reveals a popover that consists of three sections. The top section lists collaborators and provides communication buttons that can open Messages or FaceTime, the middle section contains your custom items, and the bottom section displays a button people use to manage the shared file. You don’t want to overwhelm people with too much information, so it’s crucial to offer only the most essential items that people need while they use your app to collaborate. For example, Notes summarizes the most recent updates and provides buttons that let people get more information about the updates or view more activities.
+
+![An illustration of a Notes document on iPhone. A menu is open from the Collaboration button in the document toolbar, with buttons to display the most recent updates and activities.](https://docs-assets.developer.apple.com/published/3ecf0a2e3ac684c0d5bcf8b7d54812bc/collaboration-custom-popover-notes%402x.png)
+
+**If it makes sense in your app, customize the title of the modal view’s collaboration-management button.** People choose this button — titled “Manage Shared File” by default — to reveal the collaboration-management view where they can change settings and add or remove collaborators. If you use CloudKit sharing, the system provides a management view for you; otherwise, you create your own.
+
+**Consider posting collaboration event notifications in Messages.** Choose the type of event that occurred — such as a change in the content or the collaboration membership, or the mention of a participant — and include a universal link people can use to open the relevant view in your app. For developer guidance, see [`SWHighlightEvent`](https://developer.apple.com/documentation/SharedWithYou/SWHighlightEvent).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or macOS. Not available in tvOS._
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#visionOS)
+
+By default, the system supports screen sharing for an app running in the Shared Space by streaming the current window to other collaborators. If one person transitions the app to a Full Space while sharing is in progress, the system pauses the stream for other people until the app returns to the Shared Space. For guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#watchOS)
+
+In your SwiftUI app running in watchOS, use [`ShareLink`](https://developer.apple.com/documentation/SwiftUI/ShareLink) to present the system-provided share sheet.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Related)
+
+[Activity views](https://developer.apple.com/design/human-interface-guidelines/activity-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Developer-documentation)
+
+[Shared with You](https://developer.apple.com/documentation/SharedWithYou)
+
+[`ShareLink`](https://developer.apple.com/documentation/SwiftUI/ShareLink) — SwiftUI
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/74342B30-92E9-48F3-B0F2-6E42C8FD9391/6506_wide_250x141_1x.jpg) Design for Collaboration with Messages ](https://developer.apple.com/videos/play/wwdc2022/10015)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/9785075B-13E9-4631-AD74-77B814019BF4/6589_wide_250x141_1x.jpg) Enhance collaboration experiences with Messages ](https://developer.apple.com/videos/play/wwdc2022/10095)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/39FE3E81-AB11-4FEE-AE05-37951E2ADB12/6587_wide_250x141_1x.jpg) Integrate your custom collaboration app with Messages ](https://developer.apple.com/videos/play/wwdc2022/10093)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing#Change-log)
+
+Date| Changes  
+---|---  
+December 5, 2023| Added artwork illustrating button placement and various types of collaboration permissions.  
+June 21, 2023| Updated to include guidance for visionOS.  
+September 14, 2022| New page.  
+  

package/skills/hig-patterns/references/drag-and-drop.md

@@ -0,0 +1,134 @@
+---
+title: "Drag and drop | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/drag-and-drop
+
+# Drag and drop
+
+Using drag and drop, people can move or duplicate selected photos, text, and other content by dragging the selection from one location to another.
+
+![A sketch of two overlapping squares containing an arrow pointing to the upper-left, suggesting a transition to a new destination. 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/e5f75d051f0c1030012fab8220990cc6/patterns-drag-and-drop-intro%402x.png)
+
+To perform drag and drop, people select content in one location, called the _source_ , and drop it in another, called the _destination_. These locations can be in the same container — like a text view — or in different containers, like text views on opposite sides of a split view, or even in different apps.
+
+Depending on various factors, the drag and drop action might _move_ the selected content to the destination or _copy_ it. After a successful drop, moved content exists only in the destination; copied content exists in both locations. As a general rule, dropping selected content within the same container moves it, whereas dropping content in a different container copies it. Dragging and dropping content between apps always results in a copy.
+
+People use different interactions to perform drag and drop depending on platform. For example:
+
+  * In visionOS, people pinch and hold a virtual object while dragging it to a new location in any direction, including along the z-axis.
+
+  * iOS and iPadOS support drag and drop through gestures on the touchscreen, interactions with a pointing device, and through full keyboard-access mode.
+
+  * Universal Control lets people drag content between their Mac and iPad.
+
+  * On a Mac, people can interact with a pointing device, use full keyboard access mode, or use VoiceOver to perform drag and drop.
+
+
+
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Best-practices)
+
+**As much as possible, support drag and drop throughout your app.** Most people are familiar with drag and drop and they often try it everywhere. When you use system-provided components — such as text fields and text views — you get built-in support for drag and drop.
+
+**Offer alternative ways to accomplish drag-and-drop actions.** Sometimes, drag-and-drop operations are inconvenient or impossible for people to perform, so it’s important to provide other ways to do the same things. For example, you can include menu commands that people can use to copy an item and move it to another location. In iOS and iPadOS, you can use accessibility APIs to identify sources and destinations so that people can use assistive technologies to drag and drop in your app (for developer guidance, see [`accessibilityDragSourceDescriptors`](https://developer.apple.com/documentation/ObjectiveC/NSObject-swift.class/accessibilityDragSourceDescriptors) and [`accessibilityDropPointDescriptors`](https://developer.apple.com/documentation/ObjectiveC/NSObject-swift.class/accessibilityDropPointDescriptors)).
+
+**Determine when dragging and dropping content within your app results in a move or a copy.** In general, a move makes sense when the source and destination containers are the same — such as dragging text from one location to another within a document — and a copy makes sense when they’re different, like dragging an image from one document to another. Before you change these defaults, consider the behavior that most people expect and prefer the one that is least likely to result in frustration or data loss.
+
+**Support multi-item drag and drop when it makes sense.** People appreciate the convenience of dragging a group of items to a destination, instead of dragging each item separately. In iOS, iPadOS, macOS, and visionOS, people can select multiple items and drag them as a group; macOS also lets people select multiple items from several apps and drag them as a group. In iPadOS, people can select an item, start dragging it, and add other items to the group without stopping the drag operation.
+
+**Prefer letting people undo a drag-and-drop operation.** Sometimes, people inadvertently drop content in the wrong destination, so they appreciate being able to undo the action and return to their previous state. You might also be able to help people avoid mistakes by asking for confirmation before completing a drag-and-drop operation that can’t be undone. In macOS, for example, the Finder asks for confirmation when people drag a file into a write-only folder because they won’t be able to open the folder and remove the dropped item. In some situations, it might make sense to provide a way to reverse the results of drag and drop when people can’t undo it. For example, Photos lets people cancel photo sharing after dropping a photo into a shared photo stream.
+
+**Consider offering multiple versions of dragged content, ordered from highest to lowest fidelity.** By providing multiple alternatives, the destination can choose the highest quality version it can accept. For example, if people can drag a line drawing they created in your app, you could offer a PDF vector representation, a lossless PNG image with transparency, and a lossy JPEG image without transparency, in that order. Another example is an app that uses rich, complicated objects, like charts. This app might offer the native chart object followed by a simpler version — like an image of the chart — for destinations that don’t support chart objects.
+
+**Consider supporting spring loading.** Spring loading lets people activate certain controls, like buttons and segmented controls, by dragging selected content over them. For example, Calendar lets people drag a selected event over the day, week, month, or year segments in the toolbar, giving them a convenient way to move the event to a different date. On a Mac equipped with a Magic Trackpad, a button or segmented control can activate when people force-click it while continuing to hold the content; on iPad, these components can activate when people hover over them while holding the content.
+
+## [Providing feedback](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Providing-feedback)
+
+Drag and drop is a dynamic process that can result in multiple outcomes. To help people feel in control the process, it’s crucial to provide clear and continuous feedback throughout.
+
+**Display a drag image as soon as people drag a selection about three points.** It works well to create a translucent representation of the content people are dragging. Translucency helps distinguish the representation from the original content and lets people see destinations as they pass over them. Display the drag image until people drop the content.
+
+**If it adds clarity, modify the drag image to help people predict the result of a drag-and-drop operation.** For example, when dragging a photo into a document, the drag image could expand to show the default size of the photo in the document. You can also use drag _flocking_ to visually group multiple drag items — letting people confirm that they haven’t missed an item they want to drag — and then ungroup the items when people drop them. Although changing the drag image can provide valuable feedback, avoid creating a distracting experience in which the drag image is constantly and radically changing.
+
+**Show people whether a destination can accept dragged content.** For example, you might display an insertion point or highlight a containing view only when the destination can accept a dragged item, and show no visual feedback — or an explicit “not allowed” image, like the `circle.slash` from SF Symbols — when it can’t. Display highlighting or other visual cues only while the content is positioned above the destination, removing the visual feedback when people drag the content away. When there are multiple possible destinations, provide visual cues that help people identify one at a time.
+
+**When people drop an item on an invalid destination, or when dropping fails, provide visual feedback.** For example, the item can move back from its current location to its source (if the source is still visible) or it can scale up and fade out to give the impression of the item evaporating instead of landing successfully.
+
+## [Accepting drops](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Accepting-drops)
+
+**Scroll the contents of a destination when necessary.** When people drag an item within a scrolling container that has a lot of content, the content can automatically scroll as people move the item over it. This behavior makes it easy for people to find the right place to drop the item, but if they continue the drag operation outside of the container, automatic scrolling is no longer necessary. System-provided text views and text fields behave this way by default.
+
+**When there’s a choice, pick the richest version of dropped content your app can accept.** For example, if people drag a chart object from another app, the drag operation might offer both the rich, native chart object and a simple image of it. If your app supports charts, extract and display the native chart object; it it doesn’t, use the image instead.
+
+**Extract only the relevant portion of dropped content if necessary.** For example, when people drag a contact to a recipient field in an email, Mail displays only the name and email address, not the contact’s address information.
+
+**When a physical keyboard is attached, check for the Option key at drop time.** When people hold the Option key while dragging, they can force a drag-and-drop operation within the same container to behave like a copy. If people stop holding Option before dropping content in the same container, the drag operation results in a move.
+
+**Provide feedback when dropped content needs time to transfer.** For example, you might display a progress indicator to help people estimate how long the transfer will take. In collections, lists, and tables, you might also display a placeholder at the drop location so people know where to find the content after it finishes transferring. The system can display an alert when a time-consuming transfer occurs between apps.
+
+**Provide feedback when dropped content initiates a task or action.** If people drop content onto a control that initiates a task — such as printing — show people that the task has begun and keep them informed of its progress.
+
+**Apply appropriate styling to dropped text.** When the source and destination both support the same text styles, make sure dropped text maintains its original font, typeface, size, and other attributes. Otherwise, apply the destination’s style to dropped text.
+
+**After a drop, maintain the content’s selection state in the destination, updating it in the source as needed.** People expect the content they drop to remain selected so they can immediately act on it. When the source and destination are the same container, the content disappears from its original location when the drag operation performs a move. When a drag operation within the same container performs a copy, remove the selection state from the content that remains in the original location. When people drag selected content to a different container, deselect the content in the source.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Platform-considerations)
+
+ _Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#iOS-iPadOS)
+
+**Let people perform multiple simultaneous drag activities.** In iPadOS, people can sequentially add items to an in-progress drag session, gathering as many items as their fingers can handle. For example, people can select an app icon on the Home Screen, start dragging it, and select additional app icons before dropping all of them in a different Home Screen or in a folder. To support this interaction, you need to let people add items during a drag — providing visual feedback through flocking — and accept multiple, simultaneous drops.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#macOS)
+
+**Consider letting people drag content from your app into the Finder.** When you support this, be sure to present the content in a format your app can open later. For example, Calendar lets people drag an event to the Finder as a `.ics` file. People can share this file with others or drag it back to Calendar to open it. When necessary, you can output dragged content in a _clipping_ , which is a temporary container for storing dragged content. For example, most system apps let people drag text to the Finder, where it appears as a clipping. Later, people can drag the clipping into a text field or other location that accepts text. Note that a drag-and-drop clipping isn’t related to the Clipboard.
+
+**Let people drag selected content from an inactive window without first making the window active.** Selected content in an inactive window is known as a _background selection_ and has a different appearance from selected content in the active window. In general, people expect to drag a background selection to the active window without bringing the inactive window forward.
+
+**When possible, let people drag individual items from an inactive window without affecting an existing background selection.** For example, people can drag an unselected file from an inactive Finder window without deselecting any of the window’s selected files.
+
+**Consider displaying a badge during multi-item drag operations.** A badge is a small filled oval containing a number you can use to indicate the number of items people are dragging. If a destination can accept only a subset of dragged items, update the badge to show the new number.
+
+**Consider changing the pointer appearance to indicate what will happen when people drop content.** In addition to using the _copy_ pointer, you might want to use the _drag link_ , _disappearing item_ , and _operation not allowed_ pointers, depending on the situation. For guidance, see [Pointers](https://developer.apple.com/design/human-interface-guidelines/pointing-devices#Pointers).
+
+**As much as possible, let people select and drag content with a single motion.** Unless people are selecting multiple items, they appreciate it when they don’t have to pause between making a selection and starting the drag operation.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#visionOS)
+
+**When possible, launch your app to handle content that people drop into empty space.** When you associate a user activity with draggable app content, your app can open a window or scene that handles the content when people drop it. For example, when people drop a URL into empty space, it launches Safari; when people drop Quick Look–supported content, Quick Look launches to display it. For developer guidance, see [`NSUserActivity`](https://developer.apple.com/documentation/Foundation/NSUserActivity).
+
+Video with custom controls. 
+
+Content description: A recording that shows a wearer dragging a 3D file named meteor out of a Finder window. The wearer drags the file into empty space, dropping it in an area that's visually near a table in their physical surroundings. The dropped file opens, showing a 3D meteor that appears to float above the table. 
+
+Play 
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Related)
+
+[Universal Control](https://support.apple.com/en-us/HT212757)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Developer-documentation)
+
+[Drag and drop](https://developer.apple.com/documentation/UIKit/drag-and-drop) — UIKit
+
+[Drag and Drop](https://developer.apple.com/documentation/AppKit/drag-and-drop) — AppKit
+
+[File Provider](https://developer.apple.com/documentation/FileProvider)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/9CCE8A5D-A751-441C-B88F-FB91E2D1958E/4949_wide_250x141_1x.jpg) What's new in UIKit ](https://developer.apple.com/videos/play/wwdc2021/10059)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/F93E642C-EBBD-479E-AC7F-F801103EF53F/5227_wide_250x141_1x.jpg) SwiftUI on the Mac: The finishing touches ](https://developer.apple.com/videos/play/wwdc2021/10289)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/49/5C8F0205-3AE9-4647-870B-5C10FB7EA6FF/3520_wide_250x141_1x.jpg) Designed for iPad ](https://developer.apple.com/videos/play/wwdc2020/10206)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop#Change-log)
+
+Date| Changes  
+---|---  
+October 24, 2023| Added artwork.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-patterns/references/entering-data.md

@@ -0,0 +1,69 @@
+---
+title: "Entering data | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/entering-data
+
+# Entering data
+
+When you need information from people, design ways that make it easy for them to provide it without making mistakes.
+
+![A sketch of a pencil writing within a field, suggesting data entry. 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/34d57a13e8fcf5f561a1d9c1eccf8e30/patterns-entering-data-intro%402x.png)
+
+Entering information can be a tedious process regardless of the interaction methods people use. Improve the experience by:
+
+  * Pre-gathering as much information as possible to minimize the amount of data that people need to supply
+
+  * Supporting all available input methods so people can choose the method that works for them
+
+
+
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/entering-data#Best-practices)
+
+**Get information from the system whenever possible.** Don’t ask people to enter information that you can gather automatically — such as from settings — or by getting their permission, such as their location or calendar information.
+
+**Be clear about the data you need.** For example, you might display a prompt in a text field — like “username@company.com” — or provide an introductory label that describes the information, like “Email.” You can also prefill fields with reasonable default values, which can minimize decision making and speed data entry.
+
+**Use a secure text-entry field when appropriate.** If your app or game needs sensitive data, use a field that obscures people’s input as they enter it, typically by displaying a small filled circle symbol for each character. For developer guidance, see [`SecureField`](https://developer.apple.com/documentation/SwiftUI/SecureField). In tvOS, you can also configure a [digit entry view](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views) to obscure the numerals people enter (for developer guidance, see [`isSecureDigitEntry`](https://developer.apple.com/documentation/TVUIKit/TVDigitEntryViewController/isSecureDigitEntry)). When you use the system-provided text field in visionOS, the system shows the entered data to the wearer, but not to anyone else; for example, a secure text field automatically blurs when people use AirPlay to stream their content.
+
+**Never prepopulate a password field.** Always ask people to enter their password or use biometric or keychain authentication. For guidance, see [Managing accounts](https://developer.apple.com/design/human-interface-guidelines/managing-accounts).
+
+**When possible, offer choices instead of requiring text entry.** It’s usually easier and more efficient to choose from lists of options than to type information, even when a keyboard is conveniently available. When it makes sense, consider using a picker, menu, or other selection component to give people an easy way to provide the information you need.
+
+**As much as possible, let people provide data by dragging and dropping it or by pasting it.** Supporting these interactions can ease data entry and make your experience feel more integrated with the rest of the system.
+
+**Dynamically validate field values.** People can get frustrated when they have to go back and correct mistakes after filling out a lengthy form. When you verify values as soon as people enter them — and provide feedback as soon as you detect a problem — you give them the opportunity to correct errors right away. For numeric data in particular, consider using a number formatter, which automatically configures a text field to accept only numeric values. You can also configure a formatter to display the value in a specific way, such as with a certain number of decimal places, as a percentage, or as currency.
+
+**When data entry is necessary, make sure people understand that they must provide the required data before they can proceed.** For example, if you include a Next or Continue button after a set of text fields, make the button available only after people enter the data you require.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/entering-data#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/entering-data#macOS)
+
+**Consider using an expansion tooltip to show the full version of clipped or truncated text in a field.** An _expansion tooltip_ behaves like a regular tooltip, appearing when the pointer rests on top of a field. Apps running in macOS — including iOS and iPadOS apps running on a Mac — can use an expansion tooltip to help people view the complete data they entered when a text field is too small to display it. For guidance, see [Offering help > macOS, visionOS](https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS).
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/entering-data#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/entering-data#Related)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+[Virtual keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards)
+
+[Keyboards](https://developer.apple.com/design/human-interface-guidelines/keyboards)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/entering-data#Developer-documentation)
+
+[Input events](https://developer.apple.com/documentation/SwiftUI/Input-events) — SwiftUI
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/entering-data#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/9CCE8A5D-A751-441C-B88F-FB91E2D1958E/4949_wide_250x141_1x.jpg) What's new in UIKit ](https://developer.apple.com/videos/play/wwdc2021/10059)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/entering-data#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-patterns/references/feedback.md

@@ -0,0 +1,67 @@
+---
+title: "Feedback | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/feedback
+
+# Feedback
+
+Feedback helps people know what’s happening, discover what they can do next, understand the results of actions, and avoid mistakes.
+
+![A sketch of a pointer surrounded by a circular set of short lines, suggesting a response to a mouse click. 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/d7e2c91a509e05b5e8ee422c6fea86b3/patterns-feedback-intro%402x.png)
+
+Providing clear, consistent feedback as people interact with your app or game can make it feel intuitive and encourage deeper exploration. Feedback can communicate several different things, such as:
+
+  * The current status of something
+
+  * The success or failure of an important task or action
+
+  * A warning about an action that can have negative consequences
+
+  * An opportunity to correct a mistake or problematic situation
+
+
+
+
+The most effective feedback tends to match the significance of the information to the way it’s delivered. For example, it often works well to display status information in a passive way so that people can view it when they need it. In contrast, a warning about possible data loss needs to interrupt people so they have a chance to avoid the problem.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/feedback#Best-practices)
+
+**Make sure all feedback is accessible.** When you use multiple ways to provide feedback, you reach more people and give them the opportunity to receive the feedback in ways that work for them. For example, when you provide feedback using color, text, sound, and haptics, people can receive it whether they silence their device, look away from the screen, or use VoiceOver. (For guidance on providing haptic feedback, see [Playing haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics).)
+
+**Consider integrating status feedback into your interface.** When status feedback is available near the items it describes, people get important information without having to take action or leave their current context. For example, Mail in iOS and iPadOS describes the most recent update and displays the number of unread messages in the toolbar of the mailbox screen, making the information unobtrusive but easy for people to check when they’re interested.
+
+**Use alerts to deliver critical — and ideally actionable — information.** By design, alerts disrupt the current context, so you need to match the importance of the information to the level of interruption. Alerts can lose their impact if you use them too often or to deliver unimportant information. For guidance, see [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts).
+
+**Warn people when they initiate a task that can cause data loss that’s unexpected and irreversible.** In contrast, don’t warn people when data loss is the expected result of their action. For example, the Finder doesn’t warn people every time they throw away a file because deleting the file is the expected result.
+
+**When it makes sense, confirm that a significant action or task has completed.** For example, people appreciate getting feedback that confirms a successful Apple Pay transaction. It’s generally best to reserve this type of confirmation for activities that are sufficiently important — because people typically expect their action or task to succeed, they only need to know when it doesn’t.
+
+**Show people when a command can’t be carried out and help them understand why.** For example, if people request directions without specifying a destination, Maps tells them that it can’t provide directions to and from the same location.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/feedback#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS._
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/feedback#watchOS)
+
+**Avoid displaying an indeterminate progress indicator — such as a loading indicator — in a watchOS app.** An animated indicator can make people think they need to continue paying attention to the display, which isn’t a good user experience. To provide a better experience, reassure people that they’ll receive a notification when the process completes.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/feedback#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/feedback#Related)
+
+[Playing audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio)
+
+[Playing haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics)
+
+[Motion](https://developer.apple.com/design/human-interface-guidelines/motion)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/feedback#Developer-documentation)
+
+[Animation and haptics](https://developer.apple.com/documentation/UIKit/animation-and-haptics) — UIKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/feedback#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/42/E55D60D2-C7D7-4F96-9A9D-8AF4C7D6BB49/2247_wide_250x141_1x.jpg) Designing Fluid Interfaces ](https://developer.apple.com/videos/play/wwdc2018/803)
+
+[![](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/skills/hig-patterns/references/file-management.md

@@ -0,0 +1,135 @@
+---
+title: "File management | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/file-management
+
+# File management
+
+Some apps can support documents and files that people expect to manage throughout the system.
+
+![A sketch of a document with the upper right corner folded in, suggesting interaction with files. 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/c753c4f8870e5c729becf174c1f0c5e5/patterns-file-management-intro%402x.png)
+
+Document-based apps — such as Pages, Keynote, Photos, and Preview — help people create, edit, and save documents and files, often providing customized ways for people to browse for content they want to open in the app.
+
+People also expect to browse documents without first opening a document-based app. On a Mac, for example, people use the Finder to access the macOS file system; on iPhone, iPad, and Apple Vision Pro, people use the Files app to manage the documents and files on their device. In watchOS and tvOS, people don’t typically create, edit, or manage documents, so these systems don’t provide a document-browsing interface.
+
+## [Creating and opening files](https://developer.apple.com/design/human-interface-guidelines/file-management#Creating-and-opening-files)
+
+**Use app menus and keyboard shortcuts to give people convenient ways to create and open documents.** In iPadOS and macOS, people expect to create new documents or open existing ones using familiar menu commands. When you provide commands like New or Open, iPadOS presents them in the shortcuts interface that displays when people hold the Command key on a connected hardware keyboard, and macOS presents them in the menu bar File menu. Regardless of the availability of keyboard shortcuts, include an Add (+) button to help people create a new document. In a macOS app, you put the add action in the File menu (for guidance, see [File menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#File-menu)).
+
+**If your app requires a custom file browser, support people’s understanding of the platform’s file system.** People who are familiar with the Finder and Files apps already understand the basic layout of their device’s file system. Although you might want to show the most relevant part of the file system when your custom file browser opens — for example, a Documents or iCloud folder or the most recently selected location — let people use your browser to view the rest of the file system if they want.
+
+## [Saving work](https://developer.apple.com/design/human-interface-guidelines/file-management#Saving-work)
+
+**Help people be confident that their work is always preserved unless they cancel or delete it.** In general, avoid making people take an explicit action to save their work. Instead, automatically perform periodic saves while they’re editing and when they close a file or switch to another app.
+
+**Hide file extensions by default, but let people view them if they choose.** Be sure to reflect the current choice in all the save or open interfaces you display.
+
+## [Quick Look previews](https://developer.apple.com/design/human-interface-guidelines/file-management#Quick-Look-previews)
+
+Quick Look helps you create previews of the files your app handles so that people can view them within your app and in some cases interact with them. For example, you can use Quick Look to let people listen to a preview of an audio file, add markup to a photo’s preview, or rotate and scale a 3D file preview to examine it in different ways.
+
+**Use a Quick Look viewer to let people preview a file even when your app can’t open it.** If your app lets people attach or otherwise interact with files that it doesn’t support, implementing a Quick Look viewer lets people preview those files without leaving your app.
+
+**Consider implementing a Quick Look generator if your app produces custom file types.** A Quick Look generator lets other apps — including the Finder, Files, and Spotlight — display previews of your documents, making it easier for people to find them.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/file-management#Platform-considerations)
+
+ _No additional considerations for tvOS, visionOS, or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/file-management#iOS-iPadOS)
+
+#### [Document launcher](https://developer.apple.com/design/human-interface-guidelines/file-management#Document-launcher)
+
+Starting in iOS 18 and iPadOS 18, document-based apps can use the system’s document launcher to give people a consistent, highly graphical way to browse, open, and create files. The document launcher presents a full-screen experience that highlights key elements of your app’s theme, while making it easy for people to create new documents. For developer guidance, see [`DocumentGroupLaunchScene`](https://developer.apple.com/documentation/SwiftUI/DocumentGroupLaunchScene).
+
+The document launcher consists of three main parts:
+
+  * A _title card_ that displays the app title and two app-specific buttons
+
+  * A background image that appears behind the title card and additional images — called _accessories_ — that can appear around it
+
+  * A sheet that contains a file browser and optional app-specific controls
+
+
+
+
+You can customize all three parts of the document launcher. Although the system automatically displays your app name in the title card, you specify the text and functions of the card’s primary and secondary buttons. You can also create a custom background image, one or more accessory images to surround the title card, and provide some custom controls that can appear in the file browser’s toolbar.
+
+![A screenshot of a writing app's document launcher on iPad in landscape orientation. The document launcher displays a custom background and two accessory images. At the bottom, the file browser sheet provides 3 tabs: Recents, Shared, and Browse.](https://docs-assets.developer.apple.com/published/5c3d3fe966c8f4d89b462856bec0ed24/file-management-document-launcher%402x.png)
+
+**Assign the title card’s buttons to your app’s most important functions.** The primary button typically creates a new document, and the secondary button can provide additional options. For example, the primary button in Numbers is Start Writing and the secondary button is Choose a Template.
+
+**Provide a background that’s clearly distinct from the accessories and title card.** You can use a solid color, a gradient, or a pattern. Avoid including complex images or patterns that might distract from foreground elements.
+
+**Be mindful of accessory placement.** For example, you can place accessories both in front of and behind the title card to create the appearance of depth, but you need to make sure that your app name and both buttons remain clearly visible. Avoid cluttering the title card with too many accessories, and be sure to test its overall appearance across the range of screen sizes and device orientations that you support.
+
+**Use animation sparingly.** Too much motion on the display can confuse or disorient people. If you want to animate your accessories, consider creating gentle, repeating animations that subtly highlight and enhance your app’s content. For example, you might create an animation that makes an accessory appear to breathe or sway softly. For guidance, see [Motion](https://developer.apple.com/design/human-interface-guidelines/motion).
+
+#### [File provider app extension](https://developer.apple.com/design/human-interface-guidelines/file-management#File-provider-app-extension)
+
+If your app can share its files with other apps, you can create a file provider app extension that displays a custom interface for importing, exporting, opening, and moving your app’s documents. For developer guidance, see [File Provider](https://developer.apple.com/documentation/FileProvider). An _app extension_ is code you provide that people can install and use to extend the functionality of a specific area of the system; to learn more, see [App extensions](https://developer.apple.com/app-extensions/).
+
+**When someone uses your file provider extension to open or import documents, display only documents that are appropriate in the current context.** For example, if a PDF-editing app loads your extension, only list PDF files for opening or import. You might also want to display additional information, such as modification dates, sizes, and whether documents are local or remote.
+
+**Let people select a destination when exporting and moving documents.** Unless your app stores documents in a single directory, let people navigate to a specific destination in your directory hierarchy. You could also provide a way to add new subdirectories.
+
+**Avoid including a custom top toolbar.** Your extension loads within a modal view that already includes a toolbar. Providing a second toolbar is confusing and takes space away from your content.
+
+Your app can also let people browse and open files from other apps. For developer guidance, see [Adding a document browser to your app](https://developer.apple.com/documentation/UIKit/adding-a-document-browser-to-your-app).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/file-management#macOS)
+
+#### [Custom file management](https://developer.apple.com/design/human-interface-guidelines/file-management#Custom-file-management)
+
+People have strong associations with the familiar file browsing experience of the Finder and most document-based apps. Use the default file browser unless you have an important reason to create a custom one.
+
+**Make your custom file-opening interface convenient.** For example, people might appreciate an “open recent” action in addition to the simple “open” action. You might also want to let people choose criteria on which to filter the file-browsing experience, or select multiple documents to open at once. In a macOS open panel, you can customize the title of the Open button to reflect the task — for example, if your app lets people insert a file’s contents into the current document, you might change the title to Insert.
+
+**Provide a save interface to let people change a file’s name, format, or location.** By default, a new document’s title is “Untitled” until people choose a custom name. As with a document-opening interface, a save view can also provide a browsing experience that defaults to a logical location to help people place the saved document where they want. If you support saving content in different formats, also give people a way to choose a specific file format.
+
+**Consider extending the functionality of the Save dialog.** If it makes sense in your app, you can add a custom accessory view containing useful settings or options to the Save dialog. For example, the dialog for saving Mail messages as files contains an option to include attachments.
+
+#### [Finder Sync extensions](https://developer.apple.com/design/human-interface-guidelines/file-management#Finder-Sync-extensions)
+
+If your app syncs local and remote files, you can create a Finder Sync app extension to express file synchronization status and control within the Finder. For developer guidance, see [Finder Sync](https://developer.apple.com/documentation/FinderSync).
+
+For example, you can use a Finder Sync extension to:
+
+  * Display badges in the Finder to indicate the sync status of items
+
+  * Provide custom contextual menu items that perform file and folder management tasks, like favoriting and adding password-protection
+
+  * Provide custom toolbar buttons that perform global actions, like initiating a sync operation
+
+
+
+
+**Help people avoid losing work if they turn off autosaving.** People can turn off autosaving by selecting the “Ask to keep changes when closing documents” toggle in Desktop & Dock settings. In this scenario, show that a document has unsaved changes and present a save dialog when people choose to close the document, quit your app, log out, or restart.
+
+**When autosaving is off, make sure people know when a document has unsaved changes.** To show that there are unsaved changes, display a dot on the document window’s close button and next to the document’s name in your app’s Window menu. When autosaving is on, showing a dot in these locations is confusing, because it implies that people need to take action to avoid losing their work. Regardless of autosave status, you can append “Edited” to the document’s title in the title bar, but be sure to remove this suffix as soon as autosave occurs or when people explicitly save their work.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/file-management#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/file-management#Related)
+
+[Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars)
+
+[File menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#File-menu)
+
+[Printing](https://developer.apple.com/design/human-interface-guidelines/printing)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/file-management#Developer-documentation)
+
+[Documents](https://developer.apple.com/documentation/SwiftUI/Documents) — SwiftUI
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/file-management#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/49/68960E87-E488-40C3-90E3-A820B5119FF0/3727_wide_250x141_1x.jpg) Build document-based apps in SwiftUI ](https://developer.apple.com/videos/play/wwdc2020/10039)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/file-management#Change-log)
+
+Date| Changes  
+---|---  
+June 10, 2024| Added guidelines for using the document launcher in iOS and iPadOS.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-patterns/references/going-full-screen.md

@@ -0,0 +1,79 @@
+---
+title: "Going full screen | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/going-full-screen
+
+# Going full screen
+
+iPhone, iPad, and Mac offer full-screen modes that let people expand a window to fill the screen, hiding system controls and providing a distraction-free environment.
+
+![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 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/b07f350730ba32976cba9f14829b2ce1/patterns-going-full-screen-intro%402x.png)
+
+Apple TV and Apple Watch don’t offer full-screen modes because apps and games already fill the screen by default. Apple Vision Pro doesn’t offer a full-screen mode because people can expand a window to fill more of their view or use the Digital Crown to hide passthrough and transition to a more immersive experience (for guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences)).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Best-practices)
+
+**Support full-screen mode when it makes sense for your experience.** People appreciate full-screen mode when they want to concentrate on a task or be immersed in content. Consider offering a full-screen mode if your experience lets people play a game; view media like videos or photo slideshows; or perform an in-depth task that benefits from a distraction-free environment.
+
+**If necessary, adjust your layout in full-screen mode, but don’t programmatically resize your window.** When a window is larger in full-screen mode than in non-full-screen mode, you want to keep essential content prominent while making good use of the extra space. For example, it might make sense to adjust the proportions of your interface without changing which items appear. If you make such adjustments, be sure they’re subtle enough to maintain a consistent interface and avoid causing visually jarring transitions between modes.
+
+**Continue to provide access to essential features and controls so people can complete their task without exiting full-screen mode.** For example, a full-screen media experience needs to make playback controls persistently available or easy to reveal when people need them.
+
+**Except in games, let people reveal the Dock while your iPadOS or macOS app is in full-screen mode.** In iPadOS and macOS, it’s important to preserve access to the Dock so people can quickly open other apps and Dock items. To help prevent people from accidentally revealing the Dock while they’re playing your full-screen game, you can ask iPadOS to ignore an initial swipe up from the screen’s bottom edge or hide the Dock entirely in macOS. For developer guidance, see [`preferredScreenEdgesDeferringSystemGestures`](https://developer.apple.com/documentation/SwiftUI/UIHostingController/preferredScreenEdgesDeferringSystemGestures) (SwiftUI), [`preferredScreenEdgesDeferringSystemGestures`](https://developer.apple.com/documentation/UIKit/UIViewController/preferredScreenEdgesDeferringSystemGestures) (UIKit) and [`hideDock`](https://developer.apple.com/documentation/AppKit/NSApplication/PresentationOptions-swift.struct/hideDock) (AppKit).
+
+**After people switch away from your full-screen experience, help them resume where they left off when they return.** For example, a game or a slideshow needs to pause automatically when people leave the experience so they don’t miss anything.
+
+**Let people choose when to exit full-screen mode.** People generally don’t expect full-screen mode to end automatically when they switch to a different experience or finish an absorbing activity, like playing a game or viewing a movie.
+
+**Prioritize content by temporarily hiding toolbars and navigation controls.** You can offer a distraction-free environment by hiding elements when content is the primary focus, such as when viewing full-screen photos or reading a document. If you implement such behavior, let people restore the hidden elements with a familiar gesture or action like tapping, swiping down, or moving the cursor to the top of the screen. Be sure to keep controls visible when they’re essential for navigation or performing tasks. Although a visionOS window can hide its toolbars or navigation controls, people generally expect different types of immersive experiences while wearing Apple Vision Pro; for guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Platform-considerations)
+
+ _Not supported in tvOS, visionOS, or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#iOS-iPadOS)
+
+**Consider deferring system gestures to prevent accidental exits in a full-screen app or game.** By default, the Home Screen indicator automatically hides shortly after someone switches to your app or game. It reappears when someone interacts with the bottom portion of the screen, allowing them to swipe once to exit. Whenever possible, retain this behavior because it’s familiar and what people expect. If supporting this results in unexpected exits, you can enable two swipes rather than one to exit. For developer guidance, see [`preferredScreenEdgesDeferringSystemGestures`](https://developer.apple.com/documentation/SwiftUI/UIHostingController/preferredScreenEdgesDeferringSystemGestures).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#macOS)
+
+**Use the system-provided full-screen experience.** Using the system’s full-screen support ensures that your full-screen window works well in all contexts. For example, some Mac models include a camera housing that occupies an area at the top-center of the screen. Using the system’s full-screen support automatically accommodates this area. For developer guidance, see [`toggleFullScreen(_:)`](https://developer.apple.com/documentation/AppKit/NSWindow/toggleFullScreen\(_:\)).
+
+**In a game, don’t change the display mode when players go full screen.** People expect to be in control of their display mode, and changing it automatically doesn’t improve performance.
+
+For additional developer guidance, see [Managing your game window for Metal in macOS](https://developer.apple.com/documentation/Metal/managing-your-game-window-for-metal-in-macos).
+
+**Always let people choose when to enter full-screen mode.** Prefer letting people use your window’s Enter Full Screen button, View menu item, or the Control-Command-F keyboard shortcut. Avoid offering a custom menu of window modes. In a game, you might also provide a custom [toggle](https://developer.apple.com/design/human-interface-guidelines/toggles) that turns full-screen mode on and off.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+[Multitasking](https://developer.apple.com/design/human-interface-guidelines/multitasking)
+
+[Windows](https://developer.apple.com/design/human-interface-guidelines/windows)
+
+[The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Developer-documentation)
+
+[`fullScreenCover(item:onDismiss:content:)`](https://developer.apple.com/documentation/SwiftUI/View/fullScreenCover\(item:onDismiss:content:\)) — SwiftUI
+
+[`NSScreen`](https://developer.apple.com/documentation/AppKit/NSScreen) — AppKit
+
+[`NSWindow.CollectionBehavior`](https://developer.apple.com/documentation/AppKit/NSWindow/CollectionBehavior-swift.struct) — AppKit
+
+[Managing your game window for Metal in macOS](https://developer.apple.com/documentation/Metal/managing-your-game-window-for-metal-in-macos) — Swift, Objective-C
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/873F40BE-101A-4C0D-99F0-F5C7CE7B47A3/10046_wide_250x141_1x.jpg) Elevate the design of your iPad app ](https://developer.apple.com/videos/play/wwdc2025/208)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/going-full-screen#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Updated guidance for hiding toolbars and navigation controls, and deferring Home Screen indicator gestures in full-screen iOS and iPadOS apps and games.  
+June 10, 2024| Enhanced guidance for playing a game in full-screen mode.  
+