@ngxtm/devkit 3.15.0 → 3.16.0

package/skills/hig-components-controls/references/segmented-controls.md

@@ -0,0 +1,94 @@
+---
+title: "Segmented controls | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/segmented-controls
+
+# Segmented controls
+
+A segmented control is a linear set of two or more segments, each of which functions as a button.
+
+![A stylized representation of a selected segment in a segmented control. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/89298764551d236435a7057412cf2e06/components-segmented-control-intro%402x.png)
+
+Within a segmented control, all segments are usually equal in width. Like [buttons](https://developer.apple.com/design/human-interface-guidelines/buttons), segments can contain text or images. Segments can also have text labels beneath them (or beneath the control as a whole).
+
+A segmented control offers a single choice from among a set of options, or in macOS, either a single choice or multiple choices. For example, in macOS Keynote people can select only one segment in the alignment options control to align selected text. In contrast, people can choose multiple segments in the font attributes control to combine styles like bold, italics, and underline. The toolbar of a Keynote window also uses a segmented control to let people show and hide various editing panes within the main window area.
+
+![A partial screenshot of a segmented control that consists of four text-alignment options. The center alignment option is selected.](https://docs-assets.developer.apple.com/published/7ed5112804ec078b8ba281e30a30ec85/segmented-control-one-choice%402x.png)Single choice
+
+![A partial screenshot of a segmented control that consists of four font types. Three of the four options are selected.](https://docs-assets.developer.apple.com/published/0b1d550e9c4fc6e201d45640fad819eb/segmented-control-multiple-choices%402x.png)Multiple choices
+
+In addition to representing the state of a single or multiple-choice selection, a segmented control can function as a set of buttons that perform actions without showing a selection state. For example, the Reply, Reply all, and Forward buttons in macOS Mail. For developer guidance, see [`isMomentary`](https://developer.apple.com/documentation/UIKit/UISegmentedControl/isMomentary) and [`NSSegmentedControl.SwitchTracking.momentary`](https://developer.apple.com/documentation/AppKit/NSSegmentedControl/SwitchTracking/momentary).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Best-practices)
+
+**Use a segmented control to provide closely related choices that affect an object, state, or view.** For example, a segmented control in an inspector could let people choose one or more attributes to apply to a selection, or a segmented control in a toolbar could offer a set of actions to perform on the current view.
+
+![A screenshot of the top half of the Activity screen in the iOS Health app, showing graphs of Move and Exercise activity. The segmented control above the graphs has D selected, indicating that the graphs show one day of activity.](https://docs-assets.developer.apple.com/published/f82bafe0f162b0181f6d50661109464b/segmented-controls-activity-charts%402x.png)
+
+In the iOS Health app, a segmented control provides a choice of time ranges for the activity graphs to display.
+
+**Consider a segmented control when it’s important to group functions together, or to clearly show their selection state.** Unlike other button styles, segmented controls preserve their grouping regardless of the view size or where they appear. This grouping can also help people understand at a glance which controls are currently selected.
+
+**Keep control types consistent within a single segmented control.** Don’t assign actions to segments in a control that otherwise represents selection state, and don’t show a selection state for segments in a control that otherwise performs actions.
+
+**Limit the number of segments in a control.** Too many segments can be hard to parse and time-consuming to navigate. Aim for no more than about five to seven segments in a wide interface and no more than about five segments on iPhone.
+
+**In general, keep segment size consistent.** When all segments have equal width, a segmented control feels balanced. To the extent possible, it’s best to keep icon and title widths consistent too.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Content)
+
+**Prefer using either text or images — not a mix of both — in a single segmented control.** Although individual segments can contain text labels or images, mixing the two in a single control can lead to a disconnected and confusing interface.
+
+**As much as possible, use content with a similar size in each segment.** Because all segments typically have equal width, it doesn’t look good if content fills some segments but not others.
+
+**Use nouns or noun phrases for segment labels.** Write text that describes each segment and uses [title-style capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64). A segmented control that displays text labels doesn’t need introductory text.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Platform-considerations)
+
+ _Not supported in watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#iOS-iPadOS)
+
+**Consider a segmented control to switch between closely related subviews.** A segmented control can be useful as a way to quickly switch between related subviews. For example, the segmented control in Calendar’s New Event sheet switches between the subviews for creating a new event and a new reminder. For switching between completely separate sections of an app, use a [tab bar](https://developer.apple.com/design/human-interface-guidelines/tab-bars) instead.
+
+![A screenshot of the top half of the iOS Calendar app, showing the New Event sheet. A segmented control provides the ability to switch between adding a new event and a new reminder.](https://docs-assets.developer.apple.com/published/2438acc643ee037a518cad7a15b18709/segmented-controls-calendar-new-event%402x.png)
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#macOS)
+
+**Consider using introductory text to clarify the purpose of a segmented control.** When the control uses symbols or interface icons, you could also add a label below each segment to clarify its meaning. If your app includes tooltips, provide one for each segment in a segmented control.
+
+**Use a tab view in the main window area — instead of a segmented control — for view switching.** A [tab view](https://developer.apple.com/design/human-interface-guidelines/tab-views) supports efficient view switching and is similar in appearance to a [box](https://developer.apple.com/design/human-interface-guidelines/boxes) combined with a segmented control. Consider using a segmented control to help people switch views in a toolbar or inspector pane.
+
+![A screenshot of the macOS Calendar app. The main window area shows a tab view that contains four tabs: Day, Week, Month, and Year. The sidebar shows a segmented control that contains two segments: New and Replied.](https://docs-assets.developer.apple.com/published/e0a8dd930dcd6e099b72c643b6077a7b/macos-calendar-tab-view-segmented-control-comparison%402x.png)
+
+**Consider supporting spring loading.** On a Mac equipped with a Magic Trackpad, spring loading lets people activate a segment by dragging selected items over it and force clicking without dropping the selected items. People can also continue dragging the items after a segment activates.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#tvOS)
+
+**Consider using a split view instead of a segmented control on screens that perform content filtering.** People generally find it easy to navigate back and forth between content and filtering options using a split view. Depending on its placement, a segmented control may not be as easy to access.
+
+**Avoid putting other focusable elements close to segmented controls.** Segments become selected when focus moves to them, not when people click them. Carefully consider where you position a segmented control relative to other interface elements. If other focusable elements are too close, people might accidentally focus on them when attempting to switch between segments.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#visionOS)
+
+When people look at a segmented control that uses icons, the system displays a tooltip that contains the descriptive text you supply.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Related)
+
+[Split views](https://developer.apple.com/design/human-interface-guidelines/split-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Developer-documentation)
+
+[`segmented`](https://developer.apple.com/documentation/SwiftUI/PickerStyle/segmented) — SwiftUI
+
+[`UISegmentedControl`](https://developer.apple.com/documentation/UIKit/UISegmentedControl) — UIKit
+
+[`NSSegmentedControl`](https://developer.apple.com/documentation/AppKit/NSSegmentedControl) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/segmented-controls#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-components-controls/references/sliders.md

@@ -0,0 +1,92 @@
+---
+title: "Sliders | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/sliders
+
+# Sliders
+
+A slider is a horizontal track with a control, called a thumb, that people can adjust between a minimum and maximum value.
+
+![A stylized representation of a brightness slider. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/ebb02bcf10487e6a03fd081236b35aa0/components-slider-intro%402x.png)
+
+As a slider’s value changes, the portion of track between the minimum value and the thumb fills with color. A slider can optionally display left and right icons that illustrate the meaning of the minimum and maximum values.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/sliders#Best-practices)
+
+**Customize a slider’s appearance if it adds value.** You can adjust a slider’s appearance — including track color, thumb image and tint color, and left and right icons — to blend with your app’s design and communicate intent. A slider that adjusts image size, for example, could show a small image icon on the left and a large image icon on the right.
+
+**Use familiar slider directions.** People expect the minimum and maximum sides of sliders to be consistent in all apps, with minimum values on the leading side and maximum values on the trailing side (for horizontal sliders) and minimum values at the bottom and maximum values at the top (for vertical sliders). For example, people expect to be able to move a horizontal slider that represents a percentage from 0 percent on the leading side to 100 percent on the trailing side.
+
+**Consider supplementing a slider with a corresponding text field and stepper.** Especially when a slider represents a wide range of values, people may appreciate seeing the exact slider value and having the ability to enter a specific value in a text field. Adding a stepper provides a convenient way for people to increment in whole values. For related guidance, see [Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields) and [Steppers](https://developer.apple.com/design/human-interface-guidelines/steppers).
+
+![An illustration of a horizontal linear slider without tick marks, followed by a text field and a stepper. The thumb is in the center of the slider and the text field displays 50%.](https://docs-assets.developer.apple.com/published/ce79e1e4b3b1faa688862341ed208792/sliders-text-field%402x.png)
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/sliders#Platform-considerations)
+
+ _Not supported in tvOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/sliders#iOS-iPadOS)
+
+**Don’t use a slider to adjust audio volume.** If you need to provide volume control in your app, use a volume view, which is customizable and includes a volume-level slider and a control for changing the active audio output device. For guidance, see [Playing audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/sliders#macOS)
+
+Sliders in macOS can also include tick marks, making it easier for people to pinpoint a specific value within the range.
+
+In a linear slider either with or without tick marks, the thumb is a narrow lozenge shape, and the portion of track between the minimum value and the thumb is filled with color. A linear slider often includes supplementary icons that illustrate the meaning of the minimum and maximum values.
+
+In a circular slider, the thumb appears as a small circle. Tick marks, when present, appear as evenly spaced dots around the circumference of the slider.
+
+![An illustration of a horizontal slider with the thumb in the middle. The leading portion of the track up to the thumb is filled with a blue highlight color.](https://docs-assets.developer.apple.com/published/92445cf683c4dc1b179fb5359a0bdb28/sliders-no-tick-marks%402x.png)Linear slider without tick marks
+
+![An illustration of a horizontal slider with the thumb between two tick marks in the middle of the slider. The leading portion of the track up to the thumb is filled with a blue highlight color.](https://docs-assets.developer.apple.com/published/e31ef9e35e8675bd62f695ba6a988a51/sliders-tick-marks%402x.png)Linear slider with tick marks
+
+![An illustration of a circular slider with the thumb at the 12 o'clock position.](https://docs-assets.developer.apple.com/published/3f253ed199e7e92b6124e6161dd79152/sliders-circular%402x.png)Circular slider
+
+**Consider giving live feedback as the value of a slider changes.** Live feedback shows people results in real time. For example, your Dock icons are dynamically scaled when adjusting the Size slider in Dock settings.
+
+**Choose a slider style that matches peoples’ expectations.** A horizontal slider is ideal when moving between a fixed starting and ending point. For example, a graphics app might offer a horizontal slider for setting the opacity level of an object between 0 and 100 percent. Use circular sliders when values repeat or continue indefinitely. For example, a graphics app might use a circular slider to adjust the rotation of an object between 0 and 360 degrees. An animation app might use a circular slider to adjust how many times an object spins when animated — four complete rotations equals four spins, or 1440 degrees of rotation.
+
+**Consider using a label to introduce a slider.** Labels generally use [sentence-style capitalization](https://help.apple.com/applestyleguide/#/apsgb744e4a3?sub=apdca93e113f1d64) and end with a colon. For guidance, see [Labels](https://developer.apple.com/design/human-interface-guidelines/labels).
+
+**Use tick marks to increase clarity and accuracy.** Tick marks help people understand the scale of measurements and make it easier to locate specific values.
+
+![A partial screenshot of the Energy Saver settings pane in macOS, cropped to show the slider that controls how long the display remains on after inactivity.](https://docs-assets.developer.apple.com/published/90d44ac8355f4a4e672e5e81633814e6/sliders-labels%402x.png)
+
+**Consider adding labels to tick marks for even greater clarity.** Labels can be numbers or words, depending on the slider’s values. It’s unnecessary to label every tick mark unless doing so is needed to reduce confusion. In many cases, labeling only the minimum and maximum values is sufficient. When the values of the slider are nonlinear, like in the Energy Saver settings pane, periodic labels provide context. It’s also a good idea to provide a [tooltip](https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS) that displays the value of the thumb when people hold their pointer over it.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/sliders#visionOS)
+
+**Prefer horizontal sliders.** It’s generally easier for people to gesture from side to side than up and down.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/sliders#watchOS)
+
+A slider is a horizontal track — appearing as a set of discrete steps or as a continuous bar — that represents a finite range of values. People can tap buttons on the sides of the slider to increase or decrease its value by a predefined amount.
+
+![An illustration of a watchOS volume slider with discrete steps. The first two of three steps are filled with a green highlight color, indicating the volume level.](https://docs-assets.developer.apple.com/published/3acc4339289d9cf65ec982e73f950f97/sliders-watchos-discrete%402x.png)Discrete
+
+![An illustration of a watchOS volume slider with a continuous bar. Two-thirds of the bar is filled with a green highlight color, indicating the volume level.](https://docs-assets.developer.apple.com/published/b356f0616bad32afce9ac9e62763414b/sliders-watchos-continuous%402x.png)Continuous
+
+**If necessary, create custom glyphs to communicate what the slider does.** The system displays plus and minus signs by default.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/sliders#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/sliders#Related)
+
+[Steppers](https://developer.apple.com/design/human-interface-guidelines/steppers)
+
+[Pickers](https://developer.apple.com/design/human-interface-guidelines/pickers)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/sliders#Developer-documentation)
+
+[`Slider`](https://developer.apple.com/documentation/SwiftUI/Slider) — SwiftUI
+
+[`UISlider`](https://developer.apple.com/documentation/UIKit/UISlider) — UIKit
+
+[`NSSlider`](https://developer.apple.com/documentation/AppKit/NSSlider) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/sliders#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-components-controls/references/steppers.md

@@ -0,0 +1,40 @@
+---
+title: "Steppers | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/steppers
+
+# Steppers
+
+A stepper is a two-segment control that people use to increase or decrease an incremental value.
+
+![A stylized representation of a stepper control. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/091580d0530042f6685cd17226140173/components-stepper-intro%402x.png)
+
+A stepper sits next to a field that displays its current value, because the stepper itself doesn’t display a value.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/steppers#Best-practices)
+
+**Make the value that a stepper affects obvious.** A stepper itself doesn’t display any values, so make sure people know which value they’re changing when they use a stepper.
+
+**Consider pairing a stepper with a text field when large value changes are likely.** Steppers work well by themselves for making small changes that require a few taps or clicks. By contrast, people appreciate the option to use a field to enter specific values, especially when the values they use can vary widely. On a printing screen, for example, it can help to have both a stepper and a text field to set the number of copies.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/steppers#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or visionOS. Not supported in watchOS or tvOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/steppers#macOS)
+
+**For large value ranges, consider supporting Shift-click to change the value quickly.** If your app benefits from larger changes in a stepper’s value, it can be useful to let people Shift-click the stepper to change the value by more than the default increment (by 10 times the default, for example).
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/steppers#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/steppers#Related)
+
+[Pickers](https://developer.apple.com/design/human-interface-guidelines/pickers)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/steppers#Developer-documentation)
+
+[`UIStepper`](https://developer.apple.com/documentation/UIKit/UIStepper) — UIKit
+
+[`NSStepper`](https://developer.apple.com/documentation/AppKit/NSStepper) — AppKit
+

package/skills/hig-components-controls/references/text-fields.md

@@ -0,0 +1,88 @@
+---
+title: "Text fields | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/text-fields
+
+# Text fields
+
+A text field is a rectangular area in which people enter or edit small, specific pieces of text.
+
+![A stylized representation of a text field containing a value. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/d23fbf0321063ee6b988a1528ad48ef5/components-text-field-intro%402x.png)
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/text-fields#Best-practices)
+
+**Use a text field to request a small amount of information, such as a name or an email address.** To let people input larger amounts of text, use a [text view](https://developer.apple.com/design/human-interface-guidelines/text-views) instead.
+
+**Show a hint in a text field to help communicate its purpose.** A text field can contain placeholder text — such as “Email” or “Password” — when there’s no other text in the field. Because placeholder text disappears when people start typing, it can also be useful to include a separate label describing the field to remind people of its purpose.
+
+**Use secure text fields to hide private data.** Always use a secure text field when your app asks for sensitive data, such as a password. For developer guidance, see [`SecureField`](https://developer.apple.com/documentation/SwiftUI/SecureField).
+
+**To the extent possible, match the size of a text field to the quantity of anticipated text.** The size of a text field helps people visually gauge the amount of information to provide.
+
+**Evenly space multiple text fields.** If your layout includes multiple text fields, leave enough space between them so people can easily see which input field belongs with each introductory label. Stack multiple text fields vertically when possible, and use consistent widths to create a more organized layout. For example, the first and last name fields on an address form might be one width, while the address and city fields might be a different width.
+
+**Ensure that tabbing between multiple fields flows as people expect.** When tabbing between fields, move focus in a logical sequence. The system attempts to achieve this result automatically, so you won’t need to customize this too often.
+
+**Validate fields when it makes sense.** For example, if the only legitimate value for a field is a string of digits, your app needs to alert people if they’ve entered characters other than digits. The appropriate time to check the data depends on the context: when entering an email address, it’s best to validate when people switch to another field; when creating a user name or password, validation needs to happen before people switch to another field.
+
+**Use a number formatter to help with numeric data.** A number formatter automatically configures the text field to accept only numeric values. It can also display the value in a specific way, such as with a certain number of decimal places, as a percentage, or as currency. Don’t assume the actual presentation of data, however, as formatting can vary significantly based on people’s locale.
+
+![A partial screenshot of two stacked text fields. The top field contains a number with four decimal places. The bottom field contains a currency value.](https://docs-assets.developer.apple.com/published/4c7bdd958dfd5ae5c0eb2103f511c984/text-fields-formatted-text%402x.png)Formatted text
+
+**Adjust line breaks according to the needs of the field.** By default, the system clips any text extending beyond the bounds of a text field. Alternatively, you can set up a text field to wrap text to a new line at the character or word level, or to truncate (indicated by an ellipsis) at the beginning, middle, or end.
+
+![A partial screenshot of a text field that contains a sentence that is cut off before its end.](https://docs-assets.developer.apple.com/published/4f5087014620cf61ae6e6cf691766376/text-fields-clipped-text%402x.png)Clipped text
+
+![A partial screenshot of a text field that contains a sentence that wraps to two lines.](https://docs-assets.developer.apple.com/published/5e7b94570af0f50c9e9a3061a428aa15/text-fields-wrapped-text%402x.png)Wrapped text
+
+![A partial screenshot of a text field that contains a sentence that includes an ellipsis in place of the last few words.](https://docs-assets.developer.apple.com/published/ad0040baa8369af2dbd9ab88a25c3439/text-fields-truncated-text%402x.png)Truncated text
+
+**Consider using an expansion tooltip to show the full version of clipped or truncated text.** An expansion tooltip behaves like a regular [tooltip](https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS) and appears when someone places the pointer over the field.
+
+**In iOS, iPadOS, tvOS, and visionOS apps, show the appropriate keyboard type.** Several different keyboard types are available, each designed to facilitate a different type of input, such as numbers or URLs. To streamline data entry, display the keyboard that’s appropriate for the type of content people are entering. For guidance, see [Virtual keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards).
+
+**Minimize text entry in your tvOS and watchOS apps.** Entering long passages of text or filling out numerous text fields is time-consuming on Apple TV and Apple Watch. Minimize text input and consider gathering information more efficiently, such as with buttons.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/text-fields#Platform-considerations)
+
+ _No additional considerations for tvOS or visionOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/text-fields#iOS-iPadOS)
+
+**Display a Clear button in the trailing end of a text field to help people erase their input.** When this element is present, people can tap it to clear the text field’s contents, without having to keep tapping the Delete key.
+
+**Use images and buttons to provide clarity and functionality in text fields.** You can display custom images in both ends of a text field, or you can add a system-provided button, such as the Bookmarks button. In general, use the leading end of a text field to indicate a field’s purpose and the trailing end to offer additional features, such as bookmarking.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/text-fields#macOS)
+
+**Consider using a combo box if you need to pair text input with a list of choices.** For related guidance, see [Combo boxes](https://developer.apple.com/design/human-interface-guidelines/combo-boxes).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/text-fields#watchOS)
+
+**Present a text field only when necessary.** Whenever possible, prefer displaying a list of options rather than requiring text entry.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/text-fields#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/text-fields#Related)
+
+[Text views](https://developer.apple.com/design/human-interface-guidelines/text-views)
+
+[Combo boxes](https://developer.apple.com/design/human-interface-guidelines/combo-boxes)
+
+[Entering data](https://developer.apple.com/design/human-interface-guidelines/entering-data)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/text-fields#Developer-documentation)
+
+[`TextField`](https://developer.apple.com/documentation/SwiftUI/TextField) — SwiftUI
+
+[`SecureField`](https://developer.apple.com/documentation/SwiftUI/SecureField) — SwiftUI
+
+[`UITextField`](https://developer.apple.com/documentation/UIKit/UITextField) — UIKit
+
+[`NSTextField`](https://developer.apple.com/documentation/AppKit/NSTextField) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/text-fields#Change-log)
+
+Date| Changes  
+---|---  
+June 5, 2023| Updated guidance to reflect changes in watchOS 10.  
+  

package/skills/hig-components-controls/references/text-views.md

@@ -0,0 +1,56 @@
+---
+title: "Text views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/text-views
+
+# Text views
+
+A text view displays multiline, styled text content, which can optionally be editable.
+
+![A stylized representation of a field containing text. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/21cb3b13c0de850f2eef9a9c7ec14754/components-text-view-intro%402x.png)
+
+Text views can be any height and allow scrolling when the content extends outside of the view. By default, content within a text view is aligned to the leading edge and uses the system label color. In iOS, iPadOS, and visionOS, if a text view is editable, a keyboard appears when people select the view.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/text-views#Best-practices)
+
+**Use a text view when you need to display text that’s long, editable, or in a special format.** Text views differ from [text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields) and [labels](https://developer.apple.com/design/human-interface-guidelines/labels) in that they provide the most options for displaying specialized text and receiving text input. If you need to display a small amount of text, it’s simpler to use a label or — if the text is editable — a text field.
+
+**Keep text legible.** Although you can use multiple fonts, colors, and alignments in creative ways, it’s essential to maintain the readability of your content. It’s a good idea to adopt Dynamic Type so your text still looks good if people change text size on their device. Be sure to test your content with accessibility options turned on, such as bold text. For guidance, see [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) and [Typography](https://developer.apple.com/design/human-interface-guidelines/typography).
+
+**Make useful text selectable.** If a text view contains useful information such as an error message, a serial number, or an IP address, consider letting people select and copy it for pasting elsewhere.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/text-views#Platform-considerations)
+
+ _No additional considerations for macOS, visionOS, or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/text-views#iOS-iPadOS)
+
+**Show the appropriate keyboard type.** Several different keyboard types are available, each designed to facilitate a different type of input. To streamline data entry, the keyboard you display when editing a text view needs to be appropriate for the type of content. For guidance, see [Virtual keyboards](https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards).
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/text-views#tvOS)
+
+You can display text in tvOS using a text view. Because text input in tvOS is minimal by design, tvOS uses [text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields) for editable text instead.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/text-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/text-views#Related)
+
+[Labels](https://developer.apple.com/design/human-interface-guidelines/labels)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+[Combo boxes](https://developer.apple.com/design/human-interface-guidelines/combo-boxes)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/text-views#Developer-documentation)
+
+[`Text`](https://developer.apple.com/documentation/SwiftUI/Text) — SwiftUI
+
+[`UITextView`](https://developer.apple.com/documentation/UIKit/UITextView) — UIKit
+
+[`NSTextView`](https://developer.apple.com/documentation/AppKit/NSTextView) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/text-views#Change-log)
+
+Date| Changes  
+---|---  
+June 5, 2023| Updated guidance to reflect changes in watchOS 10.  
+  

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