buildanything 1.7.1 → 2.0.0

package/skills/ios/hig-components-controls/references/toggles.md

@@ -0,0 +1,127 @@
+---
+title: "Toggles | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/toggles
+
+# Toggles
+
+A toggle lets people choose between a pair of opposing states, like on and off, using a different appearance to indicate each state.
+
+![A stylized representation of two labeled switch controls. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/f4a1d653777ba4f0b6b4b7d97d704f9f/components-toggles-intro%402x.png)
+
+A toggle can have various styles, such as switch and checkbox, and different platforms can use these styles in different ways. For guidance, see [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/toggles#Platform-considerations).
+
+In addition to toggles, all platforms also support buttons that behave like toggles by using a different appearance for each state. For developer guidance, see [`ToggleStyle`](https://developer.apple.com/documentation/SwiftUI/ToggleStyle).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/toggles#Best-practices)
+
+**Use a toggle to help people choose between two opposing values that affect the state of content or a view.** A toggle always lets people manage the state of something, so if you need to support other types of actions — such as choosing from a list of items — use a different component, like a [pop-up button](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons).
+
+**Clearly identify the setting, view, or content the toggle affects.** In general, the surrounding context provides enough information for people to understand what they’re turning on or off. In some cases, often in macOS apps, you can also supply a label to describe the state the toggle controls. If you use a button that behaves like a toggle, you generally use an interface icon that communicates its purpose, and you update its appearance — typically by changing the background — based on the current state.
+
+**Make sure the visual differences in a toggle’s state are obvious.** For example, you might add or remove a color fill, show or hide the background shape, or change the inner details you display — like a checkmark or dot — to show that a toggle is on or off. Avoid relying solely on different colors to communicate state, because not everyone can perceive the differences.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/toggles#Platform-considerations)
+
+ _No additional considerations for tvOS, visionOS, or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/toggles#iOS-iPadOS)
+
+**Use the switch toggle style only in a list row.** You don’t need to supply a label in this situation because the content in the row provides the context for the state the switch controls.
+
+**Change the default color of a switch only if necessary.** The default green color tends to work well in most cases, but you might want to use your app’s accent color instead. Be sure to use a color that provides enough contrast with the uncolored appearance to be perceptible.
+
+![An illustration of two list rows, one with an active switch toggle and one with an inactive switch toggle. The active toggle is tinted green with the standard switch color.](https://docs-assets.developer.apple.com/published/95dd06ef1de5bf4360caef804af79b15/toggles-ios-default-color%402x.png)Standard switch color
+
+![An illustration of two list rows, one with an active switch toggle and one with an inactive switch toggle. The active toggle is tinted purple with a custom switch color.](https://docs-assets.developer.apple.com/published/8e40963d32263c9319f4b5f3ac3ac721/toggles-ios-custom-color%402x.png)Custom switch color
+
+**Outside of a list, use a button that behaves like a toggle, not a switch.** For example, the Phone app uses a toggle on the filter button to let users filter their recent calls. The app adds a blue highlight to indicate when the toggle is active, and removes it when the toggle is inactive.
+
+![A screenshot of the top half of the Phone app on iPhone, showing the filtered list of recent missed calls. The filter button in the top trailing corner has a blue highlight, indicating that the toggle is active.](https://docs-assets.developer.apple.com/published/895b4c8fd67287f587d7c0576c2555a8/toggles-ios-phone-filter-on%402x.png)
+
+The Phone app uses a toggle to switch between all recent calls and various filter options. When someone chooses a filter, the toggle appears with a custom background drawn behind the symbol.
+
+![A screenshot of the top half of the Phone app on iPhone, showing all recent calls. The filter button in the top trailing corner has no highlight, indicating that the toggle is inactive.](https://docs-assets.developer.apple.com/published/d38180341155877eec2f5b34159ab72f/toggles-ios-phone-filter-off%402x.png)
+
+When someone returns to the main Recents view, the toggle appears without anything behind the symbol.
+
+**Avoid supplying a label that explains the button’s purpose.** The interface icon you create — combined with the alternative background appearances you supply — help people understand what the button does. For developer guidance, see [`changesSelectionAsPrimaryAction`](https://developer.apple.com/documentation/UIKit/UIButton/changesSelectionAsPrimaryAction).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/toggles#macOS)
+
+In addition to the switch toggle style, macOS supports the checkbox style and also defines radio buttons that can provide similar behaviors.
+
+**Use switches, checkboxes, and radio buttons in the window body, not the window frame.** In particular, avoid using these components in a toolbar or status bar.
+
+#### [Switches](https://developer.apple.com/design/human-interface-guidelines/toggles#Switches)
+
+**Prefer a switch for settings that you want to emphasize.** A switch has more visual weight than a checkbox, so it looks better when it controls more functionality than a checkbox typically does. For example, you might use a switch to let people turn on or off a group of settings, instead of just one setting. For developer guidance, see [`switch`](https://developer.apple.com/documentation/SwiftUI/ToggleStyle/switch).
+
+**Within a grouped form, consider using a mini switch to control the setting in a single row.** The height of a mini switch is similar to the height of buttons and other controls, resulting in rows that have a consistent height. If you need to present a hierarchy of settings within a grouped form, you can use a regular switch for the primary setting and mini switches for the subordinate settings. For developer guidance, see [`GroupedFormStyle`](https://developer.apple.com/documentation/SwiftUI/GroupedFormStyle) and [`ControlSize`](https://developer.apple.com/documentation/SwiftUI/ControlSize).
+
+**In general, don’t replace a checkbox with a switch.** If you’re already using a checkbox in your interface, it’s probably best to keep using it.
+
+#### [Checkboxes](https://developer.apple.com/design/human-interface-guidelines/toggles#Checkboxes)
+
+A checkbox is a small, square button that’s empty when the button is off, contains a checkmark when the button is on, and can contain a dash when the button’s state is mixed. Typically, a checkbox includes a title on its trailing side. In an editable checklist, a checkbox can appear without a title or any additional content.
+
+**Use a checkbox instead of a switch if you need to present a hierarchy of settings.** The visual style of checkboxes helps them align well and communicate grouping. By using alignment — generally along the leading edge of the checkboxes — and indentation, you can show dependencies, such as when the state of a checkbox governs the state of subordinate checkboxes.
+
+![An illustration showing a layout that includes two levels of checkboxes.](https://docs-assets.developer.apple.com/published/ec2755eb8089e275b1ebb3cd294606b0/checkbox-alignment%402x.png)
+
+**Consider using radio buttons if you need to present a set of more than two mutually exclusive options.** When people need to choose from options in addition to just “on” or “off,” using multiple radio buttons can help you clarify each option with a unique label.
+
+**Consider using a label to introduce a group of checkboxes if their relationship isn’t clear.** Describe the set of options, and align the label’s baseline with the first checkbox in the group.
+
+**Accurately reflect a checkbox’s state in its appearance.** A checkbox’s state can be on, off, or mixed. If you use a checkbox to globally turn on and off multiple subordinate checkboxes, show a mixed state when the subordinate checkboxes have different states. For example, you might need to present a text-style setting that turns all styles on or off, but also lets people choose a subset of individual style settings like bold, italic, or underline. For developer guidance, see [`allowsMixedState`](https://developer.apple.com/documentation/AppKit/NSButton/allowsMixedState).
+
+![An illustration that shows a checkbox with the on state, which looks like a small rounded square with blue fill and a white checkmark.](https://docs-assets.developer.apple.com/published/67efc6dab34453404f164acef3bac84d/checkbox-selected%402x.png)On
+
+![An illustration that shows a checkbox with the off state, which looks like a small rounded square with no fill.](https://docs-assets.developer.apple.com/published/ffd72e78175dc69a27016e8454030b71/checkbox-deselected%402x.png)Off
+
+![An illustration that shows a checkbox with the mixed state, which looks like a small rounded square with blue fill and a white hyphen.](https://docs-assets.developer.apple.com/published/f60cc3ddbea31509d83e204d963cb1d0/checkbox-mixed%402x.png)Mixed
+
+#### [Radio buttons](https://developer.apple.com/design/human-interface-guidelines/toggles#Radio-buttons)
+
+A radio button is a small, circular button followed by a label. Typically displayed in groups of two to five, radio buttons present a set of mutually exclusive choices.
+
+![An illustration that shows five items in a column, each with a radio button preceding the text Radio Button Label. The radio button for the third item is filled, indicating that it's selected.](https://docs-assets.developer.apple.com/published/dee18caa44a87ddcad53b912203b2fea/radio-button-example%402x.png)
+
+A radio button’s state is either selected (a filled circle) or deselected (an empty circle). Although a radio button can also display a mixed state (indicated by a dash), this state is rarely useful because you can communicate multiple states by using additional radio buttons. If you need to show that a setting or item has a mixed state, consider using a checkbox instead.
+
+![An illustration that shows a selected radio button, which looks like a white dot centered in a small circle with a dark fill.](https://docs-assets.developer.apple.com/published/91c45b3934ecd18b42b2bb72e64ca702/radio-button-selected%402x.png)Selected
+
+![An illustration that shows a deselected radio button, which looks like a small, empty circle.](https://docs-assets.developer.apple.com/published/1bec25f63381d81a41f885e1338eb571/radio-button-deselected%402x.png)Deselected
+
+**Prefer a set of radio buttons to present mutually exclusive options.** If you need to let people choose multiple options in a set, use checkboxes instead.
+
+**Avoid listing too many radio buttons in a set.** A long list of radio buttons takes up a lot of space in the interface and can be overwhelming. If you need to present more than about five options, consider using a component like a [pop-up button](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons) instead.
+
+**To present a single setting that can be on or off, prefer a checkbox.** Although a single radio button can also turn something on or off, the presence or absence of the checkmark in a checkbox can make the current state easier to understand at a glance. In rare cases where a single checkbox doesn’t clearly communicate the opposing states, you can use a pair of radio buttons, each with a label that specifies the state it controls.
+
+**Use consistent spacing when you display radio buttons horizontally.** Measure the space needed to accommodate the longest button label, and use that measurement consistently.
+
+![An illustration that shows three items in a row, with a radio button preceding each item. The first and third items have long text labels, while the second has a short label. The horizontal space each item occupies is equal. A filled radio button precedes the second item, indicating that it's selected.](https://docs-assets.developer.apple.com/published/95fc61aefa156d2d78d9eb6589a47f6e/radio-button-equal-spacing%402x.png)
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/toggles#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/toggles#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/toggles#Developer-documentation)
+
+[`Toggle`](https://developer.apple.com/documentation/SwiftUI/Toggle) — SwiftUI
+
+[`UISwitch`](https://developer.apple.com/documentation/UIKit/UISwitch) — UIKit
+
+[`NSButton.ButtonType.toggle`](https://developer.apple.com/documentation/AppKit/NSButton/ButtonType/toggle) — AppKit
+
+[`NSSwitch`](https://developer.apple.com/documentation/AppKit/NSSwitch) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/toggles#Change-log)
+
+Date| Changes  
+---|---  
+March 29, 2024| Enhanced guidance for using switches in macOS apps, clarified when a checkbox has a title, and added artwork for radio buttons.  
+September 12, 2023| Updated artwork.  
+  

package/skills/ios/hig-components-controls/references/token-fields.md

@@ -0,0 +1,48 @@
+---
+title: "Token fields | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/token-fields
+
+# Token fields
+
+A token field is a type of text field that can convert text into _tokens_ that are easy to select and manipulate.
+
+![A stylized representation of a text field containing a person's name formatted as a token. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/ae1ce6c362273339a9c3ec4a3538db61/components-token-field-intro%402x.png)
+
+For example, Mail uses token fields for the address fields in the compose window. As people enter recipients, Mail converts the text that represents each recipient’s name into a token. People can select these recipient tokens and drag to reorder them or move them into a different field.
+
+You can configure a token field to present people with a list of suggestions as they enter text into the field. For example, Mail suggests recipients as people type in an address field. When people select a suggested recipient, Mail inserts the recipient into the field as a token.
+
+![A partial screenshot of a Mail compose window in which tokens represent some recipients.](https://docs-assets.developer.apple.com/published/ab0f5c6dea336edb0c10cf09e33b05e3/token-fields-suggestion%402x.png)
+
+An individual token can also include a contextual menu that offers information about the token or editing options. For example, a recipient token in Mail includes a contextual menu with commands for editing the recipient name, marking the recipient as a VIP, and viewing the recipient’s contact card, among others.
+
+![A partial screenshot of a Mail compose window in which one recipient token reveals a menu of commands.](https://docs-assets.developer.apple.com/published/84d649e57814229dc2c7acb5fe5e230f/token-fields-contextual%402x.png)
+
+Tokens can also represent search terms in some situations; for guidance, see [Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/token-fields#Best-practices)
+
+**Add value with a context menu.** People often benefit from a [context menu](https://developer.apple.com/design/human-interface-guidelines/context-menus) with additional options or information about a token.
+
+**Consider providing additional ways to convert text into tokens.** By default, text people enter turns into a token whenever they type a comma. You can specify additional shortcuts, such as pressing Return, that also invoke this action.
+
+**Consider customizing the delay the system uses before showing suggested tokens.** By default, suggestions appear immediately. However, suggestions that appear too quickly may distract people while they’re typing. If your app suggests tokens, consider adjusting the delay to a comfortable level.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/token-fields#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, and watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/token-fields#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/token-fields#Related)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+[Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields)
+
+[Context menus](https://developer.apple.com/design/human-interface-guidelines/context-menus)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/token-fields#Developer-documentation)
+
+[`NSTokenField`](https://developer.apple.com/documentation/AppKit/NSTokenField) — AppKit
+

package/skills/ios/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/ios/hig-components-dialogs/SKILL.md

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

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