@ngxtm/devkit 3.15.0 → 3.17.0

package/skills/hig-components-controls/references/virtual-keyboards.md

@@ -0,0 +1,156 @@
+---
+title: "Virtual keyboards | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards
+
+# Virtual keyboards
+
+On devices without physical keyboards, the system offers various types of virtual keyboards people can use to enter data.
+
+![A stylized representation of a numeric keypad shown on top of a grid that suggests the canvas of a design tool. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/d5cea0a3ccb2af2881ade732675a1064/components-virtual-keyboard-intro%402x.png)
+
+A virtual keyboard can provide a specific set of keys that are optimized for the current task; for example, a keyboard that supports entering email addresses can include the “@” character and a period or even “.com”. A virtual keyboard doesn’t support keyboard shortcuts.
+
+When it makes sense in your app, you can replace the system-provided keyboard with a custom view that supports app-specific data entry. In iOS, iPadOS, and tvOS, you can also create an app extension that offers a custom keyboard people can install and use in place of the standard keyboard.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Best-practices)
+
+**Choose a keyboard that matches the type of content people are editing.** For example, you can help people enter numeric data by providing the numbers and punctuation keyboard. When you specify a semantic meaning for a text input area, the system can automatically provide a keyboard that matches the type of input you expect, potentially using this information to refine the keyboard corrections it offers. For developer guidance, see [`keyboardType(_:)`](https://developer.apple.com/documentation/SwiftUI/View/keyboardType\(_:\)) (SwiftUI), [`textContentType(_:)`](https://developer.apple.com/documentation/SwiftUI/View/textContentType\(_:\))(SwiftUI), [`UIKeyboardType`](https://developer.apple.com/documentation/UIKit/UIKeyboardType) (UIKit), and [`UITextContentType`](https://developer.apple.com/documentation/UIKit/UITextContentType) (UIKit).
+
+  * ASCII capable 
+  * ASCII capable number pad 
+  * Decimal pad 
+  * Default 
+  * Email address 
+  * Name phone pad 
+  * Number pad 
+  * Numbers and punctuation 
+  * Phone pad 
+  * Twitter 
+  * URL 
+  * Web search 
+
+
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, and Return keys. Typing suggestions appear above the keyboard and the Dictation button appears below it.](https://docs-assets.developer.apple.com/published/1aeba403a2942689ee8efbfed71a7943/virtual-keyboard-ascii-capable%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 10 number keys in addition to the Delete key. Keys for the numbers 2 through 9 each include the 3 or 4 letters associated with the number on a phone.](https://docs-assets.developer.apple.com/published/1da579d09964a9bd81a0823d52fa18e5/virtual-keyboard-ascii-capable-number-pad%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 10 number keys in addition to the Delete and period keys. Keys for the numbers 2 through 9 each include the 3 or 4 letters associated with the number on a phone.](https://docs-assets.developer.apple.com/published/4b43048f8d2f13d8322b95266bc4c4f3/virtual-keyboard-decimal-pad%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, and Return keys. Typing suggestions appear above the keyboard and the  Emoji and Dictation buttons appear below it.](https://docs-assets.developer.apple.com/published/34447cdc5d5eb61f1734a046f3d108c6/virtual-keyboard-default%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, period, at symbol, and Return keys. Typing suggestions appear above the keyboard and the Emoji button appears below it.](https://docs-assets.developer.apple.com/published/e7dcd10c36065774ac8cadf76b09d8e4/virtual-keyboard-email-address%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, and Return keys. Typing suggestions appear above the keyboard and the Emoji and Dictation buttons appear below it.](https://docs-assets.developer.apple.com/published/3228cd2d2cd6d36e3db1aff1d50ad903/virtual-keyboard-name-phone-pad%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 10 number keys in addition to the Delete key. Keys for the numbers 2 through 9 each include the 3 or 4 letters associated with the number on a phone.](https://docs-assets.developer.apple.com/published/679c33bdff61bc9e257982b7cffba264/virtual-keyboard-number-pad%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays 10 number and 15 punctuation keys in addition to the secondary punctuation key and the Delete, Letters, Space, and Return keys. Typing suggestions appear above the keyboard and the Dictation button appears below it.](https://docs-assets.developer.apple.com/published/916933140730b2db67f8004991c558aa/virtual-keyboard-numbers-and-punctuation%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 10 number keys in addition to the Delete key and a key for plus, star, and hash. Keys for the numbers 2 through 9 each include the 3 or 4 letters associated with the number on a phone.](https://docs-assets.developer.apple.com/published/b1b427eb7252b94e7b9d0095ccd04f56/virtual-keyboard-phone-pad%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, at symbol, and hash keys. Typing suggestions appear above the keyboard and the Emoji and Dictation buttons appear below it.](https://docs-assets.developer.apple.com/published/21b1b12df6335045a6f29efc8cbdb5a1/virtual-keyboard-twitter%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, period, slash, dot com, and Return keys. Typing suggestions appear above the keyboard and the Emoji button appears below it.](https://docs-assets.developer.apple.com/published/daec1d80ab39aff3f52effb615f84425/virtual-keyboard-url%402x.png)
+
+![A partial screenshot of a keyboard on iPhone that displays all 26 letter keys in addition to the Shift, Delete, Numbers, Space, period, and Go keys. Typing suggestions appear above the keyboard and the Emoji and Dictation buttons appear below it.](https://docs-assets.developer.apple.com/published/0618532f75b91e3f3be2416a363d4a43/virtual-keyboard-web-search%402x.png)
+
+**Consider customizing the Return key type if it helps clarify the text-entry experience.** The Return key type is based on the keyboard type you choose, but you can change this if it makes sense in your app. For example, if your app initiates a search, you can use a search Return key type rather than the standard one so the experience is consistent with other places people initiate search. For developer guidance, see [`submitLabel(_:)`](https://developer.apple.com/documentation/SwiftUI/View/submitLabel\(_:\)) (SwiftUI) and [`UIReturnKeyType`](https://developer.apple.com/documentation/UIKit/UIReturnKeyType) (UIKit).
+
+## [Custom input views](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Custom-input-views)
+
+In some cases, you can create an _input view_ if you want to provide custom functionality that enhances data-entry tasks in your app. For example, Numbers provides a custom input view for entering numeric values while editing a spreadsheet. A custom input view replaces the system-provided keyboard while people are in your app. For developer guidance, see [`ToolbarItemPlacement`](https://developer.apple.com/documentation/SwiftUI/ToolbarItemPlacement) (SwiftUI) and [`inputViewController`](https://developer.apple.com/documentation/UIKit/UIResponder/inputViewController) (UIKit).
+
+**Make sure your custom input view makes sense in the context of your app.** In addition to making data entry simple and intuitive, you want people to understand the benefits of using your custom input view. Otherwise, they may wonder why they can’t regain the system keyboard while in your app.
+
+**Play the standard keyboard sound while people type.** The keyboard sound provides familiar feedback when people tap a key on the system keyboard, so they’re likely to expect the same sound when they tap keys in your custom input view. People can turn keyboard sounds off for all keyboard interactions in Settings > Sounds. For developer guidance, see [`playInputClick()`](https://developer.apple.com/documentation/UIKit/UIDevice/playInputClick\(\)) (UIKit).
+
+## [Custom keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Custom-keyboards)
+
+In iOS, iPadOS, and tvOS, you can provide a custom keyboard that replaces the system keyboard by creating an app extension. 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/).
+
+After people choose your custom keyboard in Settings, they can use it for text entry within any app, except when editing secure text fields and phone number fields. People can choose multiple custom keyboards and switch between them at any time. For developer guidance, see [Creating a custom keyboard](https://developer.apple.com/documentation/UIKit/creating-a-custom-keyboard).
+
+Custom keyboards make sense when you want to expose unique keyboard functionality systemwide, such as a novel way of inputting text or the ability to type in a language the system doesn’t support. If you want to provide a custom keyboard for people to use only while they’re in your app, consider creating a custom input view instead.
+
+**Provide an obvious and easy way to switch between keyboards.** People know that the Globe key on the standard keyboard — which replaces the dedicated Emoji key when multiple keyboards are available — quickly switches to other keyboards, and they expect a similarly intuitive experience in your keyboard.
+
+**Avoid duplicating system-provided keyboard features.** On some devices, the Emoji/Globe key and Dictation key automatically appear beneath the keyboard, even when people are using custom keyboards. Your app can’t affect these keys, and it’s likely to be confusing if you repeat them in your keyboard.
+
+**Consider providing a keyboard tutorial in your app.** People are used to the standard keyboard, and learning how to use a new keyboard can take time. You can help make the process easier by providing usage instructions in your app — for example, you might tell people how to choose your keyboard, activate it during text entry, use it, and switch back to the standard keyboard. Avoid displaying help content within the keyboard itself.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Platform-considerations)
+
+ _Not supported in macOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#iOS-iPadOS)
+
+**Use the keyboard layout guide to make the keyboard feel like an integrated part of your interface.** Using the layout guide also helps you keep important parts of your interface visible while the virtual keyboard is onscreen. For developer guidance, see [Adjusting your layout with keyboard layout guide](https://developer.apple.com/documentation/UIKit/adjusting-your-layout-with-keyboard-layout-guide).
+
+![An illustration of an app layout on iPhone, showing two stacked text fields and a button above the keyboard.](https://docs-assets.developer.apple.com/published/2d310619deb1ce3587596b7fee6e5b08/ui-fully-visible%402x.png)
+
+![A checkmark in a circle to indicate a correct example.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)The keyboard layout guide helps ensure that app UI and the keyboard work well together.
+
+![An illustration of an app layout on iPhone, showing two stacked text fields. The keyboard covers part of the bottom text field.](https://docs-assets.developer.apple.com/published/b2612a1b69632d398d2744caee9ff1e2/text-field-hidden%402x.png)
+
+![An X in a circle to indicate an incorrect example.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)Without the layout guide, the keyboard could make entering text more difficult.
+
+![An illustration of an app layout on iPhone, showing two stacked text fields and a button above the keyboard. The keyboard covers part of the button.](https://docs-assets.developer.apple.com/published/3a2b1c460427926e69f4d3e8d1383aef/button-hidden%402x.png)
+
+![An X in a circle to indicate an incorrect example.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)Without the layout guide, the keyboard could make tapping a button more difficult.
+
+**Place custom controls above the keyboard thoughtfully.** Some apps position an input accessory view containing custom controls above the keyboard to offer app-specific functionality related to the data people are working with. For example, Numbers displays controls that help people apply standard or custom calculations to spreadsheet data. If your app offers custom controls that augment the keyboard, make sure they’re relevant to the current task. If other views in your app use Liquid Glass, or if your view looks out of place above the keyboard, apply Liquid Glass to the view that contains your controls to maintain consistency. If you use a standard toolbar to contain your controls, it automatically adopts Liquid Glass. Use the keyboard layout guide and standard padding to ensure the system positions your controls as expected within the view. For developer guidance, see [`ToolbarItemPlacement`](https://developer.apple.com/documentation/SwiftUI/ToolbarItemPlacement) (SwiftUI), [`inputAccessoryView`](https://developer.apple.com/documentation/UIKit/UIResponder/inputAccessoryView) (UIKit), and [`UIKeyboardLayoutGuide`](https://developer.apple.com/documentation/UIKit/UIKeyboardLayoutGuide) (UIKit).
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#tvOS)
+
+tvOS displays a linear virtual keyboard when people select a text field using the Siri Remote.
+
+Note
+
+A grid keyboard screen appears when people use devices other than the Siri Remote, and the layout of content automatically adapts to the keyboard.
+
+When people activate a digit entry view, tvOS displays a digit-specific keyboard. For guidance, see [Digit entry views](https://developer.apple.com/design/human-interface-guidelines/digit-entry-views).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#visionOS)
+
+In visionOS, the system-provided virtual keyboard supports both direct and indirect gestures and appears in a separate window that people can move where they want. You don’t need to account for the location of the keyboard in your layouts.
+
+Video with custom controls. 
+
+Content description: A recording showing a person typing on a virtual keyboard in visionOS. 
+
+Play 
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#watchOS)
+
+On Apple Watch, a text field can show a keyboard if the device screen is large enough. Otherwise, the system lets people use dictation or Scribble to enter information. You can’t change the keyboard type in watchOS, but you can set the content type of the text field. The system uses this information to make text entry easier, such as by offering suggestions. For developer guidance, see [`textContentType(_:)`](https://developer.apple.com/documentation/SwiftUI/View/textContentType\(_:\)) (SwiftUI).
+
+People can also use a nearby paired iPhone to enter text on Apple Watch.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Related)
+
+[Entering data](https://developer.apple.com/design/human-interface-guidelines/entering-data)
+
+[Keyboards](https://developer.apple.com/design/human-interface-guidelines/keyboards)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Developer-documentation)
+
+[`keyboardType(_:)`](https://developer.apple.com/documentation/SwiftUI/View/keyboardType\(_:\)) — SwiftUI
+
+[`textContentType(_:)`](https://developer.apple.com/documentation/SwiftUI/View/textContentType\(_:\)) — SwiftUI
+
+[`UIKeyboardType`](https://developer.apple.com/documentation/UIKit/UIKeyboardType) — UIKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Added guidance for displaying custom controls above the keyboard, and updated to reflect virtual keyboard availability in watchOS.  
+February 2, 2024| Clarified the virtual keyboard’s support for direct and indirect gestures in visionOS.  
+December 5, 2023| Added artwork for visionOS.  
+June 21, 2023| Changed page title from Onscreen keyboards and updated to include guidance for visionOS.  
+  

package/skills/hig-components-dialogs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: hig-components-dialogs
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for presentation components including alerts, action sheets,
+  popovers, sheets, and digit entry views. Use this skill when the user says
+  "should I use an alert or a sheet," "how do I show a confirmation dialog,"
+  "when should I use a popover," "my modals are annoying users," or asks about
+  alert design, action sheet, popover, sheet, modal, dialog, digit entry,
+  confirmation dialog, warning dialog, modal presentation, non-modal content,
+  destructive action confirmation, or overlay UI patterns. Cross-references:
+  hig-components-menus, hig-components-controls, hig-components-search,
+  hig-patterns.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Presentation 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. **Alerts: sparingly, for critical situations.** Errors needing attention, destructive action confirmations, or information requiring acknowledgment. They interrupt flow and demand a response.
+
+2. **Sheets: focused tasks that maintain context.** Slides in from the edge (or attaches to a window on macOS). Use for creating items, editing settings, multi-step forms.
+
+3. **Popovers: non-modal on iPad and Mac.** Appear next to the trigger element, dismissed by tapping outside. For additional information, options, or controls without taking over the screen.
+
+4. **Action sheets: choosing among actions.** Present when picking from multiple actions, especially if one is destructive. iPhone: slide up from bottom. iPad: appear as popovers.
+
+5. **Minimize interruptions.** Before reaching for a modal, consider inline presentation or making the action undoable instead.
+
+6. **Concise, actionable alert text.** Short descriptive title. Brief message body if needed. Button labels should be specific verbs ("Delete", "Save"), not "OK".
+
+7. **Mark destructive actions clearly.** Destructive button style (red text). Place destructive buttons where users are less likely to tap reflexively.
+
+8. **Provide a cancel option** for alerts and action sheets with multiple actions. On action sheets, cancel appears at the bottom, separated.
+
+9. **Digit entry: focused and accessible.** Appropriately sized input fields, automatic advancement between digits, support for paste and autofill.
+
+10. **Adapt presentation to platform.** The same interaction may use different components on iPhone, iPad, Mac, and visionOS.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [alerts.md](references/alerts.md) | Alerts | Button ordering, title/message text, confirmation, destructive actions |
+| [action-sheets.md](references/action-sheets.md) | Action sheets | Multiple actions, cancel option, destructive handling |
+| [popovers.md](references/popovers.md) | Popovers | Non-modal, dismiss on tap outside, iPad/Mac |
+| [sheets.md](references/sheets.md) | Sheets | Modal task, context preservation |
+| [digit-entry-views.md](references/digit-entry-views.md) | Digit entry | PIN input, autofill, auto-advance |
+
+## Output Format
+
+1. **Recommended presentation type with rationale** and why alternatives are less suitable.
+2. **Content guidelines** -- title, message, button labels per Apple's tone and brevity rules.
+3. **Dismiss behavior** -- how the user dismisses and what happens (save, discard, cancel).
+4. **Alternatives** -- when the scenario might not need a modal at all (inline feedback, undo, progressive disclosure).
+
+## Questions to Ask
+
+1. What information or action does the presentation need?
+2. Blocking or non-blocking?
+3. Which platforms?
+4. How often does this appear?
+
+## Related Skills
+
+- **hig-components-menus** -- Buttons and toolbar items triggering presentations
+- **hig-components-controls** -- Input controls within sheets and popovers
+- **hig-components-search** -- Search and navigation within presented views
+- **hig-patterns** -- Modality, interruptions, user flow management
+- **hig-foundations** -- Color, typography, layout for presentation components
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

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

@@ -0,0 +1,74 @@
+---
+title: "Action sheets | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/action-sheets
+
+# Action sheets
+
+An action sheet is a modal view that presents choices related to an action people initiate.
+
+![A stylized representation of a set of action sheet buttons at the bottom of an iPhone. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/6102d0ab9e98aa9149e6a929f0576d75/components-action-sheet-intro%402x.png)
+
+Developer note
+
+When you use SwiftUI, you can offer action sheet functionality in all platforms by specifying a [presentation modifier](https://developer.apple.com/documentation/swiftui/view-presentation) for a confirmation dialog. If you use UIKit, you use the [`UIAlertController.Style.actionSheet`](https://developer.apple.com/documentation/UIKit/UIAlertController/Style/actionSheet) to display an action sheet in iOS, iPadOS, and tvOS.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/action-sheets#Best-practices)
+
+**Use an action sheet — not an alert — to offer choices related to an intentional action.** For example, when people cancel the message they’re editing in Mail on iPhone, an action sheet provides two choices: delete the draft, or save the draft. 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. More importantly, an alert is usually unexpected, generally telling people about a problem or a change in the current situation that might require them to act. For guidance, see [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts).
+
+![A partial screenshot of a new message being composed in Mail on iPhone.](https://docs-assets.developer.apple.com/published/d78e3a39898532655eb9155586cdc1e7/action-sheet-iphone-mail%402x.png)
+
+![A partial screenshot of a new message being composed in Mail on iPhone, with the action sheet open after choosing to cancel the message. The action sheet presents choices to delete the draft or save the draft.](https://docs-assets.developer.apple.com/published/fedd171df9ff41645c885d3a428bc190/action-sheet-iphone-mail-delete-action%402x.png)
+
+**Use action sheets sparingly.** Action sheets give people important information and choices, but they interrupt the current task to do so. To encourage people to pay attention to action sheets, avoid using them more than necessary.
+
+**Aim to keep titles short enough to display on a single line.** A long title is difficult to read quickly and might get truncated or require people to scroll.
+
+**Provide a message only if necessary.** In general, the title — combined with the context of the current action — provides enough information to help people understand their choices.
+
+**If necessary, provide a Cancel button that lets people reject an action that might destroy data.** Place the Cancel button at the bottom of the action sheet (or in the upper-left corner of the sheet in watchOS). A SwiftUI confirmation dialog includes a Cancel button by default.
+
+**Make destructive choices visually prominent.** Use the destructive style for buttons that perform destructive actions, and place these buttons at the top of the action sheet where they tend to be most noticeable. For developer guidance, see [`destructive`](https://developer.apple.com/documentation/SwiftUI/ButtonRole/destructive) (SwiftUI) or [`UIAlertAction.Style.destructive`](https://developer.apple.com/documentation/UIKit/UIAlertAction/Style-swift.enum/destructive) (UIKit).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/action-sheets#Platform-considerations)
+
+ _No additional considerations for macOS or tvOS. Not supported in visionOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/action-sheets#iOS-iPadOS)
+
+**Use an action sheet — not a menu — to provide choices related to an action.** People are accustomed to having an action sheet appear when they perform an action that might require clarifying choices. In contrast, people expect a menu to appear when they choose to reveal it.
+
+**Avoid letting an action sheet scroll.** The more buttons an action sheet has, the more time and effort it takes for people to make a choice. Also, scrolling an action sheet can be hard to do without inadvertently tapping a button.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/action-sheets#watchOS)
+
+The system-defined style for action sheets includes a title, an optional message, a Cancel button, and one or more additional buttons. The appearance of this interface is different depending on the device.
+
+![An illustration of an action sheet on Apple Watch, showing content that represents text in the top half of the watch screen and two stacked buttons in the bottom half.](https://docs-assets.developer.apple.com/published/4ec6a46689c0ec4550d6fe48d4aa27a8/action-sheet-watch-system-defined%402x.png)
+
+Each button has an associated style that conveys information about the button’s effect. There are three system-defined button styles:
+
+Style| Meaning  
+---|---  
+Default| The button has no special meaning.  
+Destructive| The button destroys user data or performs a destructive action in the app.  
+Cancel| The button dismisses the view without taking any action.  
+  
+**Avoid displaying more than four buttons in an action sheet, including the Cancel button.** When there are fewer buttons onscreen, it’s easier for people to view all their options at once. Because the Cancel button is required, aim to provide no more than three additional choices.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/action-sheets#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/action-sheets#Related)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+[Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets)
+
+[Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/action-sheets#Developer-documentation)
+
+[`confirmationDialog(_:isPresented:titleVisibility:actions:)`](https://developer.apple.com/documentation/SwiftUI/View/confirmationDialog\(_:isPresented:titleVisibility:actions:\)-46zbb) — SwiftUI
+
+[`UIAlertController.Style.actionSheet`](https://developer.apple.com/documentation/UIKit/UIAlertController/Style/actionSheet) — UIKit
+

package/skills/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/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/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
+