buildanything 1.7.1 → 2.0.0

package/skills/ios/hig-components-dialogs/references/alerts.md

@@ -0,0 +1,158 @@
+---
+title: "Alerts | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/alerts
+
+# Alerts
+
+An alert gives people critical information they need right away.
+
+![A stylized representation of an alert mockup that includes a title, description, primary button, and secondary button. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/89439ba152693e294fbb3298c00b2b48/components-alert-intro%402x.png)
+
+For example, an alert can tell people about a problem, warn them when their action might destroy data, and give them an opportunity to confirm a purchase or another important action they initiated.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/alerts#Best-practices)
+
+**Use alerts sparingly.** Alerts give people important information, but they interrupt the current task to do so. Encourage people to pay attention to your alerts by making certain that each one offers only essential information and useful actions.
+
+**Avoid using an alert merely to provide information.** People don’t appreciate an interruption from an alert that’s informative, but not actionable. If you need to provide only information, prefer finding an alternative way to communicate it within the relevant context. For example, when a server connection is unavailable, Mail displays an indicator that people can choose to learn more.
+
+**Avoid displaying alerts for common, undoable actions, even when they’re destructive.** For example, you don’t need to alert people about data loss every time they delete an email or file because they do so with the intention of discarding data, and they can undo the action. In comparison, when people take an uncommon destructive action that they can’t undo, it’s important to display an alert in case they initiated the action accidentally.
+
+**Avoid showing an alert when your app starts.** If you need to inform people about new or important information the moment they open your app, design a way to make the information easily discoverable. If your app detects a problem at startup, like no network connection, consider alternative ways to let people know. For example, you could show cached or placeholder data and a nonintrusive label that describes the problem.
+
+## [Anatomy](https://developer.apple.com/design/human-interface-guidelines/alerts#Anatomy)
+
+An alert is a modal view that can look different in different platforms and devices.
+
+  * iOS 
+  * macOS 
+  * tvOS 
+  * visionOS 
+  * watchOS 
+
+
+
+![An illustration of an alert in the middle of the screen on iPhone.](https://docs-assets.developer.apple.com/published/ec9df875e228750105a393c96279bea5/alert-ios%402x.png)
+
+![An illustration of an alert in the middle of the screen on a Mac.](https://docs-assets.developer.apple.com/published/0dfc6fd9de495ce3b7201169d829d760/alert-macos%402x.png)
+
+![An illustration of an alert on tvOS.](https://docs-assets.developer.apple.com/published/63dde83c2b156231420f095a4d9dfae3/alert-tvos%402x.jpg)
+
+![An illustration of an alert on Apple Vision Pro.](https://docs-assets.developer.apple.com/published/1abb6467cc401af501648da039b2b317/alert-visionos%402x.png)
+
+![An illustration of an alert on Apple Watch.](https://docs-assets.developer.apple.com/published/a452534204f5ddb4aaa6ba7679946f2e/alert-watchos%402x.png)
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/alerts#Content)
+
+In all platforms, alerts display a title, optional informative text, and up to three buttons. On some platforms, alerts can include additional elements.
+
+  * In iOS, iPadOS, macOS, and visionOS, an alert can include a text field.
+
+  * Alerts in macOS and visionOS can include an icon and an accessory view.
+
+  * macOS alerts can add a suppression [checkbox](https://developer.apple.com/design/human-interface-guidelines/toggles#Checkboxes) and a [Help button](https://developer.apple.com/design/human-interface-guidelines/buttons#Help-buttons).
+
+
+
+
+**In all alert copy, be direct, and use a neutral, approachable tone.** Alerts often describe problems and serious situations, so avoid being oblique or accusatory, or masking the severity of the issue.
+
+**Write a title that clearly and succinctly describes the situation.** You need to help people quickly understand the situation, so be complete and specific, without being verbose. As much as possible, describe what happened, the context in which it happened, and why. Avoid writing a title that doesn’t convey useful information — like “Error” or “Error 329347 occurred” — but also avoid overly long titles that wrap to more than two lines. If the title is a complete sentence, use [sentence-style capitalization](https://help.apple.com/applestyleguide/#/apsgb744e4a3?sub=apdca93e113f1d64) and appropriate ending punctuation. If the title is a sentence fragment, use title-style capitalization, and don’t add ending punctuation.
+
+**Include informative text only if it adds value.** If you need to add an informative message, keep it as short as possible, using complete sentences, sentence-style capitalization, and appropriate punctuation.
+
+**Avoid explaining alert buttons.** If your alert text and button titles are clear, you don’t need to explain what the buttons do. In rare cases where you need to provide guidance on choosing a button, use a term like _choose_ to account for people’s current device and interaction method, and refer to a button using its exact title without quotes. For guidance, see [Buttons](https://developer.apple.com/design/human-interface-guidelines/alerts#Buttons).
+
+**If supported, include a text field only if you need people’s input to resolve the situation.** For example, you might need to present a secure text field to receive a password.
+
+## [Buttons](https://developer.apple.com/design/human-interface-guidelines/alerts#Buttons)
+
+**Create succinct, logical button titles.** Aim for a one- or two-word title that describes the result of selecting the button. Prefer verbs and verb phrases that relate directly to the alert text — for example, “View All,” “Reply,” or “Ignore.” In informational alerts only, you can use “OK” for acceptance, avoiding “Yes” and “No.” Always use “Cancel” to title a button that cancels the alert’s action. As with all button titles, use [title-style capitalization](https://help.apple.com/applestyleguide/#/apsgb744e4a3?sub=apdca93e113f1d64) and no ending punctuation.
+
+**Avoid using OK as the default button title unless the alert is purely informational.** The meaning of “OK” can be unclear even in alerts that ask people to confirm that they want to do something. For example, does “OK” mean “OK, I want to complete the action” or “OK, I now understand the negative results my action would have caused”? A specific button title like “Erase,” “Convert,” “Clear,” or “Delete” helps people understand the action they’re taking.
+
+**Place buttons where people expect.** In general, place the button people are most likely to choose on the trailing side in a row of buttons or at the top in a stack of buttons. Always place the default button on the trailing side of a row or at the top of a stack. Cancel buttons are typically on the leading side of a row or at the bottom of a stack.
+
+**Use the destructive style to identify a button that performs a destructive action people didn’t deliberately choose.** For example, when people deliberately choose a destructive action — such as Empty Trash — the resulting alert doesn’t apply the destructive style to the Empty Trash button because the button performs the person’s original intent. In this scenario, the convenience of pressing Return to confirm the deliberately chosen Empty Trash action outweighs the benefit of reaffirming that the button is destructive. In contrast, people appreciate an alert that draws their attention to a button that can perform a destructive action they didn’t originally intend.
+
+**If there’s a destructive action, include a Cancel button to give people a clear, safe way to avoid the action.** Always use the title “Cancel” for a button that cancels an alert’s action. Note that you don’t want to make a Cancel button the default button. If you want to encourage people to read an alert and not just automatically press Return to dismiss it, avoid making any button the default button. Similarly, if you must display an alert with a single button that’s also the default, use a Done button, not a Cancel button.
+
+**Provide alternative ways to cancel an alert when it makes sense.** In addition to choosing a Cancel button, people appreciate using keyboard shortcuts or other quick ways to cancel an onscreen alert. For example:
+
+Action| Platform  
+---|---  
+Exit to the Home Screen| iOS, iPadOS  
+Pressing Escape (Esc) or Command-Period (.) on an attached keyboard| iOS, iPadOS, macOS, visionOS  
+Pressing Menu on the remote| tvOS  
+  
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/alerts#Platform-considerations)
+
+ _No additional considerations for tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/alerts#iOS-iPadOS)
+
+**Use an action sheet — not an alert — to offer choices related to an intentional action.** For example, when people cancel the Mail message they’re editing, an action sheet provides three choices: delete the edits (or the entire draft), save the draft, or return to editing. Although an alert can also help people confirm or cancel an action that has destructive consequences, it doesn’t provide additional choices related to the action. For guidance, see [Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets).
+
+**When possible, avoid displaying an alert that scrolls.** Although an alert might scroll if the text size is large enough, be sure to minimize the potential for scrolling by keeping alert titles short and including a brief message only when necessary.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/alerts#macOS)
+
+macOS automatically displays your app icon in an alert, but you can supply an alternative icon or symbol. In addition, macOS lets you:
+
+  * Configure repeating alerts to let people suppress subsequent occurrences of the same alert.
+
+  * Append a custom view if it’s necessary to provide additional information (for developer guidance, see [`accessoryView`](https://developer.apple.com/documentation/AppKit/NSAlert/accessoryView)).
+
+  * Include a Help button that opens your help documentation (see [Help buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Help-buttons)).
+
+
+
+
+**Use a caution symbol sparingly.** Using a caution symbol like `exclamationmark.triangle` too frequently in your alerts diminishes its significance. Use the symbol only when extra attention is really needed, as when confirming an action that might result in unexpected loss of data. Don’t use the symbol for tasks whose only purpose is to overwrite or remove data, such as a save or empty trash.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/alerts#visionOS)
+
+When your app is running in the Shared Space, visionOS displays an alert in front of the app’s window, slightly forward along the z-axis.
+
+Video with custom controls. 
+
+Content description: A video of an alert in the Freeform app running in the Shared Space in visionOS. When the video plays, someone chooses to permanently delete a recently deleted Freeform board. An alert then appears in front of the Freeform window to ask for confirmation. 
+
+Play 
+
+If someone moves a window without dismissing its alert, the alert remains anchored to the window. If your app is running in a Full Space, the system displays the alert centered in the wearer’s [field of view](https://developer.apple.com/design/human-interface-guidelines/spatial-layout#Field-of-view).
+
+Video with custom controls. 
+
+Content description: A video of an alert in the Freeform app running in the Shared Space in visionOS. When the video plays, someone chooses to permanently delete a recently deleted Freeform board. An alert then appears in front of the Freeform window to ask for confirmation. The alert is not dismissed and remains anchored to the Freeform window as it’s moved around the Shared Space. 
+
+Play 
+
+If you need to display an accessory view in a visionOS alert, create a view that has a maximum height of 154 pt and a 16-pt corner radius.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/alerts#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/alerts#Related)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+[Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets)
+
+[Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/alerts#Developer-documentation)
+
+[`alert(_:isPresented:actions:)`](https://developer.apple.com/documentation/SwiftUI/View/alert\(_:isPresented:actions:\)-1bkka) — SwiftUI
+
+[`UIAlertController`](https://developer.apple.com/documentation/UIKit/UIAlertController) — UIKit
+
+[`NSAlert`](https://developer.apple.com/documentation/AppKit/NSAlert) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/alerts#Change-log)
+
+Date| Changes  
+---|---  
+February 2, 2024| Enhanced guidance for using default and Cancel buttons.  
+September 12, 2023| Added anatomy artwork for visionOS.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/ios/hig-components-dialogs/references/digit-entry-views.md

@@ -0,0 +1,32 @@
+---
+title: "Digit entry views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/digit-entry-views
+
+# Digit entry views
+
+A digit entry view fills the entire screen and prompts people to enter a series of digits, like a PIN, using a digit-specific keyboard.
+
+![A stylized representation of an Apple TV five-digit passcode entry screen. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/ca37bff0e0176a587241e4a6ced6090d/components-digit-entry-view-intro%402x.png)
+
+You can add an optional title and prompt above the line of digits.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views#Best-practices)
+
+**Use secure digit fields.** Secure digit fields display asterisks instead of the entered digit onscreen. Always use a secure digit field when your app asks for sensitive data.
+
+**Clearly state the purpose of the digit entry view.** Use a title and prompt that explains why someone needs to enter digits.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, macOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views#Related)
+
+[Virtual keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views#Developer-documentation)
+
+[`TVDigitEntryViewController`](https://developer.apple.com/documentation/TVUIKit/TVDigitEntryViewController) — TVUIKit
+

package/skills/ios/hig-components-dialogs/references/popovers.md

@@ -0,0 +1,81 @@
+---
+title: "Popovers | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/popovers
+
+# Popovers
+
+A popover is a transient view that appears above other content when people click or tap a control or interactive area.
+
+![A stylized representation of a popover view. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/90068cb259f3c3d15e6adf38766dd706/components-popover-intro%402x.png)
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/popovers#Best-practices)
+
+**Use a popover to expose a small amount of information or functionality.** Because a popover disappears after people interact with it, limit the amount of functionality in the popover to a few related tasks. For example, a calendar event popover makes it easy for people to change the date or time of an event, or to move it to another calendar. The popover disappears after the change, letting people continue reviewing the events on their calendar.
+
+**Consider using popovers when you want more room for content.** Views like sidebars and panels take up a lot of space. If you need content only temporarily, displaying it in a popover can help streamline your interface.
+
+**Position popovers appropriately.** Make sure a popover’s arrow points as directly as possible to the element that revealed it. Ideally, a popover doesn’t cover the element that revealed it or any essential content people may need to see while using it.
+
+**Use a Close button for confirmation and guidance only.** A Close button, including Cancel or Done, is worth including if it provides clarity, like exiting with or without saving changes. Otherwise, a popover generally closes when people click or tap outside its bounds or select an item in the popover. If multiple selections are possible, make sure the popover remains open until people explicitly dismiss it or they click or tap outside its bounds.
+
+**Always save work when automatically closing a nonmodal popover.** People can unintentionally dismiss a nonmodal popover by clicking or tapping outside its bounds. Discard people’s work only when they click or tap an explicit Cancel button.
+
+**Show one popover at a time.** Displaying multiple popovers clutters the interface and causes confusion. Never show a cascade or hierarchy of popovers, in which one emerges from another. If you need to show a new popover, close the open one first.
+
+**Don’t show another view over a popover.** Make sure nothing displays on top of a popover, except for an alert.
+
+**When possible, let people close one popover and open another with a single click or tap.** Avoiding extra gestures is especially desirable when several different bar buttons each open a popover.
+
+**Avoid making a popover too big.** Make a popover only big enough to display its contents and point to the place it came from. If necessary, the system can adjust the size of a popover to ensure it fits well in the interface.
+
+**Provide a smooth transition when changing the size of a popover.** Some popovers provide both condensed and expanded views of the same information. If you adjust the size of a popover, animate the change to avoid giving the impression that a new popover replaced the old one.
+
+**Avoid using the word _popover_ in help documentation.** Instead, refer to a specific task or selection. For example, instead of “Select the Show button at the bottom of the popover,” you might write “Select the Show button.”
+
+**Avoid using a popover to show a warning.** People can miss a popover or accidentally close it. If you need to warn people, use an [alert](https://developer.apple.com/design/human-interface-guidelines/alerts) instead.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/popovers#Platform-considerations)
+
+ _No additional considerations for visionOS. Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/popovers#iOS-iPadOS)
+
+**Avoid displaying popovers in compact views.** Make your app or game dynamically adjust its layout based on the size class of the content area. Reserve popovers for wide views; for compact views, use all available screen space by presenting information in a full-screen modal view like a sheet instead. For related guidance, see [Modality](https://developer.apple.com/design/human-interface-guidelines/modality).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/popovers#macOS)
+
+You can make a popover detachable in macOS, which becomes a separate panel when people drag it. The panel remains visible onscreen while people interact with other content.
+
+  * Attached popover 
+  * Detached popover 
+
+
+
+![An illustration of an event in Calendar with the attached version of the event's popover next to and pointing to it.](https://docs-assets.developer.apple.com/published/ef05d3cb071e4c11209cce39b596ca99/attached-popover%402x.png)
+
+![An illustration of an event in Calendar with the detached version of the event's popover next to it.](https://docs-assets.developer.apple.com/published/d0b16d14a582a887f385896669394ee4/detached-popover%402x.png)
+
+**Consider letting people detach a popover.** People might appreciate being able to convert a popover into a panel if they want to view other information while the popover remains visible.
+
+**Make minimal appearance changes to a detached popover.** A panel that looks similar to the original popover helps people maintain context.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/popovers#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/popovers#Related)
+
+[Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets)
+
+[Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets)
+
+[Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/popovers#Developer-documentation)
+
+[`popover(isPresented:attachmentAnchor:arrowEdge:content:)`](https://developer.apple.com/documentation/SwiftUI/View/popover\(isPresented:attachmentAnchor:arrowEdge:content:\)) — SwiftUI
+
+[`UIPopoverPresentationController`](https://developer.apple.com/documentation/UIKit/UIPopoverPresentationController) — UIKit
+
+[`NSPopover`](https://developer.apple.com/documentation/AppKit/NSPopover) — AppKit
+

package/skills/ios/hig-components-dialogs/references/sheets.md

@@ -0,0 +1,157 @@
+---
+title: "Sheets | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/sheets
+
+# Sheets
+
+A sheet helps people perform a scoped task that’s closely related to their current context.
+
+![A stylized representation of a sheet extending down from the top of a window. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/357ff0b017e9241da82888bd3aec4372/components-sheet-intro%402x.png)
+
+By default, a sheet is _modal_ , presenting a targeted experience that prevents people from interacting with the parent view until they dismiss the sheet (for more on modal presentation, see [Modality](https://developer.apple.com/design/human-interface-guidelines/modality)). A modal sheet is useful for requesting specific information from people or presenting a simple task that they can complete before returning to the parent view. For example, a sheet might let people supply information needed to complete an action, such as attaching a file, choosing the location for a move or save, or specifying the format for a selection.
+
+In macOS, visionOS, and watchOS, a sheet is always modal, but in iOS and iPadOS, a sheet can also be nonmodal. When a nonmodal sheet is onscreen, people use its functionality to directly affect the current task in the parent view without dismissing the sheet. For example, Notes on iPhone and iPad uses a nonmodal sheet to help people apply different formatting to various text selections as they edit a note.
+
+![A screenshot of an in-progress note on iPhone. Several words are selected and highlighted. In the bottom half of the screen, the format sheet shows that the selected words use the regular body font.](https://docs-assets.developer.apple.com/published/56830eea369c54ce82f6867a0907f3f3/sheets-nonmodal-notes-text-regular%402x.png)
+
+The Notes format sheet lets people apply formatting to selected text in the editing view.
+
+![A screenshot of the same in-progress note on iPhone. Different words are selected and highlighted. The format sheet shows that the selected words use the body font in italics.](https://docs-assets.developer.apple.com/published/f7b427fb2d880e16df4ed1025a43b47c/sheets-nonmodal-notes-text-italic%402x.png)
+
+Because the sheet is nonmodal, people can make additional text selections without dismissing the sheet.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/sheets#Best-practices)
+
+**Use a sheet to present simple content or tasks.** A sheet allows some of the parent view to remain visible, helping people retain their original context as they interact with the sheet.
+
+**For complex or prolonged user flows, consider alternatives to sheets.** For example, iOS and iPadOS offer a full-screen style of modal view that can work well to display content like videos, photos, or camera views or to help people perform multistep tasks like document or photo editing. (For developer guidance, see [`UIModalPresentationStyle.fullScreen`](https://developer.apple.com/documentation/UIKit/UIModalPresentationStyle/fullScreen).) In a macOS experience, you might want to open a new window or let people enter full-screen mode instead of using a sheet. For example, a self-contained task like editing a document tends to work well in a separate window, whereas [going full screen](https://developer.apple.com/design/human-interface-guidelines/going-full-screen) can help people view media. In visionOS, you can give people a way to transition your app to a Full Space where they can dive into content or a task; for guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences).
+
+**Display only one sheet at a time from the main interface.** When people close a sheet, they expect to return to the parent view or window. If closing a sheet takes people back to another sheet, they can lose track of where they are in your app. If something people do within a sheet results in another sheet appearing, close the first sheet before displaying the new one. If necessary, you can display the first sheet again after people dismiss the second one.
+
+**Use a nonmodal view when you want to present supplementary items that affect the main task in the parent view.** To give people access to information and actions they need while continuing to interact with the main window, consider using a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views) in visionOS or a [panel](https://developer.apple.com/design/human-interface-guidelines/panels) in macOS; in iOS and iPadOS, you can use a nonmodal sheet for this workflow. For guidance, see [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/sheets#iOS-iPadOS).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/sheets#Platform-considerations)
+
+ _No additional considerations for tvOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/sheets#iOS-iPadOS)
+
+A resizable sheet expands when people scroll its contents or drag the _grabber_ , which is a small horizontal indicator that can appear at the top edge of a sheet. Sheets resize according to their _detents_ , which are particular heights at which a sheet naturally rests. Designed for iPhone, detents specify particular heights at which a sheet naturally rests. The system defines two detents: _large_ is the height of a fully expanded sheet and _medium_ is about half of the fully expanded height.
+
+![An illustration showing an iPhone screen in portrait orientation containing a solid rounded rectangle that occupies almost all of the screen, representing a full-screen sheet. A rounded close button appears in the upper-left corner of the sheet.](https://docs-assets.developer.apple.com/published/c2a600adb5237892585d71d2ae61c9a6/sheets-large-detent%402x.png)
+
+Large detent
+
+![An illustration showing an iPhone screen in portrait orientation containing a solid rounded rectangle that occupies half of the screen, representing a half-screen sheet. A rounded close button appears in the upper-left corner of the sheet.](https://docs-assets.developer.apple.com/published/413ac0d4cf462891f2ba9d0cd4bb01f1/sheets-medium-detent%402x.png)
+
+Medium detent
+
+Sheets automatically support the large detent. Adding the medium detent allows the sheet to rest at both heights, whereas specifying only medium prevents the sheet from expanding to full height. For developer guidance, see [`detents`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController/detents).
+
+**In an iPhone app, consider supporting the medium detent to allow progressive disclosure of the sheet’s content.** For example, a share sheet displays the most relevant items within the medium detent, where they’re visible without resizing. To view more items, people can scroll or expand the sheet. In contrast, you might not want to support the medium detent if a sheet’s content is more useful when it displays at full height. For example, the compose sheets in Messages and Mail display only at full height to give people enough room to create content.
+
+**Include a grabber in a resizable sheet.** A grabber shows people that they can drag the sheet to resize it; they can also tap it to cycle through the detents. In addition to providing a visual indicator of resizability, a grabber also works with VoiceOver so people can resize the sheet without seeing the screen. For developer guidance, see [`prefersGrabberVisible`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController/prefersGrabberVisible).
+
+**Support swiping to dismiss a sheet.** People expect to swipe vertically to dismiss a sheet instead of tapping a dismiss button. If people have unsaved changes in the sheet when they begin swiping to dismiss it, use an action sheet to let them confirm their action.
+
+**Position Done and Cancel buttons as people expect.** Typically, a Done or Dismiss button belongs in a sheet’s top-right corner in a left-to-right layout. The Cancel button belongs in a sheet’s top-left corner.
+
+The exception to this is for sheets with additional subviews, where the Cancel button belongs in the top-right; this provides room for the Back button in the top-left on pages after the first. At the end of the navigation flow, replace the Cancel button with the Done button.
+
+![An illustration of the top half of a sheet on iPhone. A Cancel button appears in the top-left corner of the view.](https://docs-assets.developer.apple.com/published/4c0ea03add08b05592c51ed58ebb79f1/sheets-close-button-placement-no-back%402x.png)
+
+Placement of the Cancel button when it appears by itself
+
+![An illustration of the top half of a sheet on iPhone. A Back button appears in the top-left corner of the view, and a Cancel button appears in the top-right corner.](https://docs-assets.developer.apple.com/published/4325d8e5db78c585b01a7137e34189c7/sheets-close-button-placement-with-back%402x.png)
+
+Placement of the Cancel button when it appears as part of a multi-step flow
+
+**Prefer using the page or form sheet presentation styles in an iPadOS app.** Each style uses a default size for the sheet, centering its content on top of a dimmed background view and providing a consistent experience. For developer guidance, see [`UIModalPresentationStyle`](https://developer.apple.com/documentation/UIKit/UIModalPresentationStyle).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/sheets#macOS)
+
+In macOS, a sheet is a cardlike view with rounded corners that floats on top of its parent window. The parent window is dimmed while the sheet is onscreen, signaling that people can’t interact with it until they dismiss the sheet. However, people expect to interact with other app windows before dismissing a sheet.
+
+![A screenshot of the Notes app, with the What's New in Notes sheet centered on top of a dimmed Notes document in the background.](https://docs-assets.developer.apple.com/published/582e02d0df9b4a07dea002053f9ec6ea/sheets-macos-notes%402x.png)
+
+**Present a sheet in a reasonable default size.** People don’t generally expect to resize sheets, so it’s important to use a size that’s appropriate for the content you display. In some cases, however, people appreciate a resizable sheet — such as when they need to expand the contents for a clearer view — so it’s a good idea to support resizing.
+
+**Let people interact with other app windows without first dismissing a sheet.** When a sheet opens, you bring its parent window to the front — if the parent window is a document window, you also bring forward its modeless document-related panels. When people want to interact with other windows in your app, make sure they can bring those windows forward even if they haven’t dismissed the sheet yet.
+
+**Position a sheet’s dismiss buttons as people expect.** People expect to find all buttons that dismiss a sheet — including Done, OK, and Cancel — at the bottom of the view, in the trailing corner.
+
+**Use a panel instead of a sheet if people need to repeatedly provide input and observe results.** A find and replace panel, for example, might let people initiate replacements individually, so they can observe the result of each search for correctness. For guidance, see [Panels](https://developer.apple.com/design/human-interface-guidelines/panels).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/sheets#visionOS)
+
+While a sheet is visible in a visionOS app, it floats in front of its parent window, dimming it, and becoming the target of people’s interactions with the app.
+
+Video with custom controls. 
+
+Content description: A recording showing a sheet opening above a blank window in visionOS. 
+
+Play 
+
+**Avoid displaying a sheet that emerges from the bottom edge of a window.** To help people view the sheet, prefer centering it in their [field of view](https://developer.apple.com/design/human-interface-guidelines/spatial-layout#Field-of-view).
+
+**Present a sheet in a default size that helps people retain their context.** Avoid displaying a sheet that covers most or all of its window, but consider letting people resize the sheet if they want.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/sheets#watchOS)
+
+In watchOS, a sheet is a full-screen view that slides over your app’s current content. The sheet is semitransparent to help maintain the current context, but the system applies a material to the background that blurs and desaturates the covered content.
+
+![A screenshot of a sheet with a primary Action button and a default cancel button on Apple Watch.](https://docs-assets.developer.apple.com/published/fcdad96a098bea9c7b98a114403e46f2/sheets-watch-overlay%402x.png)
+
+**Use a sheet only when your modal task requires a custom title or custom content presentation.** If you need to give people important information or present a set of choices, consider using an [alert](https://developer.apple.com/design/human-interface-guidelines/alerts) or [action sheet](https://developer.apple.com/design/human-interface-guidelines/action-sheets).
+
+**Keep sheet interactions brief and occasional.** Use a sheet only as a temporary interruption to the current workflow, and only to facilitate an important task. Avoid using a sheet to help people navigate your app’s content.
+
+**Change the default label of the dismiss control only if it makes sense in your app.** By default, the sheet displays a round Cancel button in the upper left corner. Use this button when the sheet lets people make changes to the app’s behavior or to their data. If your sheet simply presents information without enabling a task, use the standard Done button instead. You can use a [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars) to display multiple buttons.
+
+![A screenshot of a watch displaying a sheet with the standard check mark Done button on Apple Watch.](https://docs-assets.developer.apple.com/published/bc70ac8a01bd110befa02132e9f53672/sheets-watch-custom%402x.png)
+
+The standard Done button
+
+**If you change the default label, prefer using SF Symbols to represent the action.** Avoid using a label that might mislead people into thinking that the sheet is part of a hierarchical navigation interface. Also, if the text in the top-leading corner looks like a page or app title, people won’t know how to dismiss the sheet. For guidance, see [Standard icons](https://developer.apple.com/design/human-interface-guidelines/icons#Standard-icons).
+
+![A screenshot that shows a top toolbar with the default Cancel button at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/4b2b3901392b3a2101bf98fbee0b7809/modal-sheet-watchos-do%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
+
+![A screenshot that shows a top toolbar with a custom Back button at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/3342cdf046b51d5b7e22008f4fa36cf8/modal-sheet-watchos-do-not-1%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+![A screenshot that shows a top toolbar with a button with the words Page title at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/7e655a4130904ed5def637dde60325f9/modal-sheet-watchos-do-not-2%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/sheets#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/sheets#Related)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+[Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets)
+
+[Popovers](https://developer.apple.com/design/human-interface-guidelines/popovers)
+
+[Panels](https://developer.apple.com/design/human-interface-guidelines/panels)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/sheets#Developer-documentation)
+
+[`sheet(item:onDismiss:content:)`](https://developer.apple.com/documentation/SwiftUI/View/sheet\(item:onDismiss:content:\)) — SwiftUI
+
+[`UISheetPresentationController`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController) — UIKit
+
+[`presentAsSheet(_:)`](https://developer.apple.com/documentation/AppKit/NSViewController/presentAsSheet\(_:\)) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/sheets#Change-log)
+
+Date| Changes  
+---|---  
+March 29, 2024| Added guidance to use form or page sheet styles in iPadOS apps.  
+December 5, 2023| Recommended using a split view to offer supplementary items in a visionOS app.  
+June 21, 2023| Updated to include guidance for visionOS.  
+June 5, 2023| Updated guidance for using sheets in watchOS.  
+  

package/skills/ios/hig-components-layout/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: hig-components-layout
+version: 1.0.0
+description: >-
+  Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user
+  asks about "sidebar", "split view", "tab bar", "tab view", "scroll view", "window design", "panel",
+  "list view", "table view", "column view", "outline view", "navigation structure", "app layout",
+  "boxes", "ornaments", or organizing content hierarchically in Apple apps.
+  Also use when the user says "how should I organize my app", "what navigation pattern should I use",
+  "my layout breaks on iPad", "how do I build a sidebar", "should I use tabs or a sidebar",
+  or "my app doesn't adapt to different screen sizes".
+  Cross-references: hig-foundations for layout/spacing principles, hig-platforms for platform-specific
+  navigation, hig-patterns for multitasking and full-screen, hig-components-content for content display.
+---
+
+# Apple HIG: Layout and Navigation Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Organize hierarchically.** Structure information from broad categories to specific details. Sidebars for top-level sections, lists for browsable items, detail views for individual content.
+
+2. **Use standard navigation patterns.** Tab bars for flat navigation between peer sections (iPhone). Sidebars for deep hierarchical navigation (iPad, Mac). Match the pattern to the information architecture and platform.
+
+3. **Adapt to screen size.** Three-column on iPad collapses to single-column on iPhone. Use size classes and adaptive APIs (NavigationSplitView) for automatic adaptation.
+
+4. **Support multitasking on iPad.** Respond gracefully to Split View, Slide Over, and Stage Manager. Test at every split ratio and size class transition.
+
+5. **Maintain spatial consistency on visionOS.** Windows, volumes, and ornaments in shared space. Position predictably. Use ornaments for toolbars and controls without occluding content.
+
+6. **Use scroll views for overflow content.** Enable paging for discrete content units. Support pull-to-refresh where appropriate. Respect safe areas.
+
+7. **Keep navigation predictable.** Users should always know where they are, how they got there, and how to go back. Use back buttons, breadcrumbs, and clear section titles.
+
+8. **Prefer system components.** UINavigationController, UISplitViewController, NavigationSplitView, and TabView provide built-in adaptivity, accessibility, and state restoration.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [sidebars.md](references/sidebars.md) | Sidebars | Source lists, selection state, collapsible sections, iPad/Mac patterns |
+| [column-views.md](references/column-views.md) | Column Views | Finder-style browsing, progressive disclosure through columns |
+| [outline-views.md](references/outline-views.md) | Outline Views | Expandable hierarchies, disclosure triangles, tree structures |
+| [split-views.md](references/split-views.md) | Split Views | Two/three column layouts, NavigationSplitView, adaptive collapse |
+| [tab-views.md](references/tab-views.md) | Tab Views | Segmented tabs, page-style tabs, macOS tab grouping |
+| [tab-bars.md](references/tab-bars.md) | Tab Bars | Bottom tab bars (iOS), badge counts, max tab count |
+| [scroll-views.md](references/scroll-views.md) | Scroll Views | Paging, scroll indicators, content insets, pull-to-refresh |
+| [windows.md](references/windows.md) | Windows | macOS/visionOS window management, sizing, full-screen, restoration |
+| [panels.md](references/panels.md) | Panels | Inspector panels, utility panels, floating panels, macOS conventions |
+| [lists-and-tables.md](references/lists-and-tables.md) | Lists and Tables | Plain/grouped/inset-grouped styles, swipe actions, section headers |
+| [boxes.md](references/boxes.md) | Boxes | Content grouping containers, labeled boxes, macOS grouping |
+| [ornaments.md](references/ornaments.md) | Ornaments | visionOS toolbar attachments, positioning, visibility |
+
+## Navigation Pattern Selection
+
+| App Structure | Recommended Pattern | Platform Adaptation |
+|---|---|---|
+| 3-5 peer top-level sections | Tab Bar | iPhone: bottom tab bar. iPad: sidebar (`.sidebarAdaptable`, iPadOS 18+). Mac: sidebar or toolbar tabs |
+| Deep hierarchical content | Sidebar + NavigationSplitView | iPhone: single column stack. iPad: two/three columns. Mac: full multi-column |
+| Deep file/folder tree | Column View | Mac: Finder-style. iPad: adaptable. iPhone: push navigation |
+| Flat list with detail | Split View (two column) | iPhone: push/pop stack. iPad/Mac: primary + detail columns |
+| Document-based with inspectors | Window + Panels | Mac: main window with inspector. iPad: sheet or popover |
+| Spatial app with tools | Window + Ornaments | visionOS: ornaments on window. Other platforms: toolbars |
+
+## Layout Adaptation Checklist
+
+- [ ] **Compact width (iPhone portrait):** Navigation collapses to single stack? Tab bars visible?
+- [ ] **Regular width (iPad landscape, Mac):** Navigation expands to sidebar + detail? Space used well?
+- [ ] **Multitasking (iPad):** Adapts at every split ratio? Works in Slide Over?
+- [ ] **Accessibility:** Supports Dynamic Type at all sizes? VoiceOver order logical?
+- [ ] **Orientation:** Content reflows between portrait and landscape?
+- [ ] **visionOS:** Windows positioned ergonomically? Ornaments accessible? Depth meaningful?
+
+## Output Format
+
+1. **Recommended navigation pattern** with rationale for the app's information architecture.
+2. **Layout hierarchy** from root container down (e.g., TabView > NavigationSplitView > List > Detail).
+3. **Platform adaptation** across targeted platforms and size classes.
+4. **Size class behavior** at each transition.
+
+## Questions to Ask
+
+1. What is the app's information architecture? (Sections, hierarchy depth, top-level categories?)
+2. How many top-level sections?
+3. Which platforms?
+4. Need multitasking on iPad?
+5. SwiftUI or UIKit?
+
+## Related Skills
+
+- **hig-foundations** -- Layout spacing, margins, safe areas, alignment
+- **hig-platforms** -- Platform-specific navigation conventions
+- **hig-patterns** -- Multitasking, full-screen, and launching patterns
+- **hig-components-content** -- Content displayed within layout containers
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*

package/skills/ios/hig-components-layout/references/boxes.md

@@ -0,0 +1,48 @@
+---
+title: "Boxes | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/boxes
+
+# Boxes
+
+A box creates a visually distinct group of logically related information and components.
+
+![A stylized representation of a group of interface elements within a rounded rectangle. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/6e253271e9888e8d596d1d5b601d90f3/components-box-intro%402x.png)
+
+By default, a box uses a visible border or background color to separate its contents from the rest of the interface. A box can also include a title.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/boxes#Best-practices)
+
+**Prefer keeping a box relatively small in comparison with its containing view.** As a box’s size gets close to the size of the containing window or screen, it becomes less effective at communicating the separation of grouped content, and it can crowd other content.
+
+**Consider using padding and alignment to communicate additional grouping within a box.** A box’s border is a distinct visual element — adding nested boxes to define subgroups can make your interface feel busy and constrained.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/boxes#Content)
+
+**Provide a succinct introductory title if it helps clarify the box’s contents.** The appearance of a box helps people understand that its contents are related, but it might make sense to provide more detail about the relationship. Also, a title can help VoiceOver users predict the content they encounter within the box.
+
+**If you need a title, write a brief phrase that describes the contents.** Use sentence-style capitalization. Avoid ending punctuation unless you use a box in a settings pane, where you append a colon to the title.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/boxes#Platform-considerations)
+
+ _No additional considerations for visionOS. Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/boxes#iOS-iPadOS)
+
+By default, iOS and iPadOS use the secondary and tertiary background [colors](https://developer.apple.com/design/human-interface-guidelines/color) in boxes.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/boxes#macOS)
+
+By default, macOS displays a box’s title above it.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/boxes#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/boxes#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/boxes#Developer-documentation)
+
+[`GroupBox`](https://developer.apple.com/documentation/SwiftUI/GroupBox) — SwiftUI
+
+[`NSBox`](https://developer.apple.com/documentation/AppKit/NSBox) — AppKit
+