@ngxtm/devkit 3.14.0 → 3.16.0

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

@@ -0,0 +1,93 @@
+---
+name: hig-components-controls
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for selection and input controls including pickers, toggles,
+  sliders, steppers, segmented controls, combo boxes, text fields, text views,
+  labels, token fields, virtual keyboards, rating indicators, and gauges. Use
+  this skill when the user says "picker or segmented control," "how should my
+  form look," "what keyboard type should I use," "toggle vs checkbox," or asks
+  about picker design, toggle, switch, slider, stepper, text field, text input,
+  segmented control, combo box, label, token field, virtual keyboard, rating
+  indicator, gauge, form design, input validation, or control state management.
+  Cross-references: hig-components-menus, hig-components-dialogs,
+  hig-components-search.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Selection and Input Controls
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Clear current state.** Users must always see what is selected. Toggles show on/off, segmented controls highlight the active segment, pickers display the current selection.
+
+2. **Prefer standard system controls.** Built-in controls provide consistency and accessibility. Custom controls introduce a learning curve and may break assistive features.
+
+3. **Toggles for binary states.** On or off. In Settings-style screens, changes take effect immediately. In modal forms, changes commit on confirmation.
+
+4. **Segmented controls for mutually exclusive options.** 2-5 items, roughly equal importance, short labels.
+
+5. **Sliders for continuous values.** When precise numeric input is not critical. Provide min/max labels or icons for range endpoints.
+
+6. **Pickers for long option lists.** Too many options for a segmented control. Works well for dates, times, structured data.
+
+7. **Steppers for small, precise adjustments.** Increment/decrement in fixed steps. Display current value next to the stepper with reasonable min/max bounds.
+
+8. **Text fields for short, single-line input.** Text views for multi-line. Configure keyboard type to match expected input (email, URL, number).
+
+9. **Combo boxes: text input + selection list.** macOS. Type a value or choose from a predefined list when custom values are valid.
+
+10. **Token fields: discrete values as visual tokens.** macOS. For email recipients, tags, or collections of discrete items.
+
+11. **Gauges and rating indicators display values.** Gauges show a value within a range. Rating indicators show ratings (often stars). Display-only; use interactive variants for input.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [controls.md](references/controls.md) | General controls | States, affordance, system controls |
+| [toggles.md](references/toggles.md) | Toggles | On/off, immediate effect |
+| [segmented-controls.md](references/segmented-controls.md) | Segmented controls | 2-5 options, equal weight |
+| [sliders.md](references/sliders.md) | Sliders | Continuous range, min/max labels |
+| [steppers.md](references/steppers.md) | Steppers | Fixed steps, bounded values |
+| [pickers.md](references/pickers.md) | Pickers | Dates, times, long option sets |
+| [combo-boxes.md](references/combo-boxes.md) | Combo boxes | macOS, type or select, custom values |
+| [text-fields.md](references/text-fields.md) | Text fields | Short input, keyboard types, validation |
+| [text-views.md](references/text-views.md) | Text views | Multi-line, comments, descriptions |
+| [labels.md](references/labels.md) | Labels | Placement, VoiceOver support |
+| [token-fields.md](references/token-fields.md) | Token fields | macOS, chips, tags, recipients |
+| [virtual-keyboards.md](references/virtual-keyboards.md) | Virtual keyboards | Email, URL, number keyboard types |
+| [rating-indicators.md](references/rating-indicators.md) | Rating indicators | Star ratings, display-only |
+| [gauges.md](references/gauges.md) | Gauges | Level indicators, range display |
+
+## Output Format
+
+1. **Control recommendation with rationale** and why alternatives are less suitable.
+2. **State management** -- how the control communicates current state and whether changes apply immediately or on confirmation.
+3. **Validation approach** -- when to show errors and how to communicate rules.
+4. **Accessibility** -- labels, traits, hints for VoiceOver.
+
+## Questions to Ask
+
+1. What type of data? (Boolean, choice from fixed set, numeric, free-form text?)
+2. How many options?
+3. Which platforms? (Combo boxes and token fields are macOS-only)
+4. Settings screen or inline form?
+
+## Related Skills
+
+- **hig-components-menus** -- Buttons and pop-up buttons complementing selection controls
+- **hig-components-dialogs** -- Sheets and popovers containing forms
+- **hig-components-search** -- Search fields sharing text input patterns
+- **hig-inputs** -- Keyboard, pointer, gesture interactions with controls
+- **hig-foundations** -- Typography, color, layout for control styling
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/hig-components-controls/references/combo-boxes.md

@@ -0,0 +1,40 @@
+---
+title: "Combo boxes | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/combo-boxes
+
+# Combo boxes
+
+A combo box combines a text field with a pull-down button in a single control.
+
+![A stylized representation of a combo box control displaying a list of cities. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/8f828536eb509b9cd023583ecd2f8eca/components-combobox-intro%402x.png)
+
+People can enter a custom value into the field or click the button to choose from a list of predefined values. When people enter a custom value, it’s not added to the list of choices.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/combo-boxes#Best-practices)
+
+**Populate the field with a meaningful default value from the list.** Although the field can be empty by default, it’s best when the default value refers to the hidden choices. The default value doesn’t have to be the first item in the list.
+
+**Use an introductory label to let people know what types of items to expect.** Generally, use title-style capitalization for labels and end them with a colon. For related guidance, see [Labels](https://developer.apple.com/design/human-interface-guidelines/labels).
+
+**Provide relevant choices.** People appreciate the ability to enter a custom value, as well as the convenience of choosing from a list of the most likely choices.
+
+**Make sure list items aren’t wider than the text field.** If an item is too wide, the text field might truncate it, which is hard for people to read.
+
+For guidance, see [Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields) and [Pull-down buttons](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/combo-boxes#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/combo-boxes#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/combo-boxes#Related)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+[Pull-down buttons](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/combo-boxes#Developer-documentation)
+
+[`NSComboBox`](https://developer.apple.com/documentation/AppKit/NSComboBox) — AppKit
+

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

@@ -0,0 +1,112 @@
+---
+title: "Controls | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/controls
+
+# Controls
+
+In iOS and iPadOS, a control provides quick access to a feature of your app from Control Center, the Lock Screen, or the Action button.
+
+![A partial screenshot of controls in Control Center, such as the Airplane Mode toggle, Wi-Fi toggle, and AirPlay button. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/0cea7197d96a9a3bfadc6aed2942b027/components-controls-intro%402x.png)
+
+A control is a button or toggle that provides quick access to your app’s features from other areas of the system. Control buttons perform an action, link to a specific area of your app, or launch a [camera experience on a locked device](https://developer.apple.com/design/human-interface-guidelines/controls#Camera-experiences-on-a-locked-device). Control toggles switch between two states, such as on and off.
+
+People can add controls to Control Center by pressing and holding in an empty area of Control Center, to the Lock Screen by customizing their Lock Screen, and to the Action button by configuring the Action button in the Settings app.
+
+## [Anatomy](https://developer.apple.com/design/human-interface-guidelines/controls#Anatomy)
+
+Controls contain a symbol image, a title, and, optionally, a value. The symbol visually represents what the control does and can be a symbol from [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) or a custom symbol. The title describes what the control relates to, and the value represents the state of the control. For example, the title can display the name of a light in a room, while the value can display whether it’s on or off.
+
+![A diagram showing the placement of the symbol image, the title, and the value for a control toggle.](https://docs-assets.developer.apple.com/published/df1b5eb2796a6452c640b746948df228/control-medium-anatomy%402x.png)
+
+Controls display their information differently depending on where they appear:
+
+  * In Control Center, a control displays its symbol and, at larger sizes, its title and value.
+
+  * On the Lock Screen, a control displays its symbol.
+
+  * On iPhone devices with a control assigned to the Action button, pressing and holding it displays the control’s symbol in the Dynamic Island, as well as its value (if present).
+
+
+
+
+![A partial screenshot of Control Center on iPhone, highlighting that the Silent mode control is active, with a symbol of a bell with a line drawn through it and red tint.](https://docs-assets.developer.apple.com/published/01a84972ab485b0b33d4342bd1b1a42a/control-control-center%402x.png)
+
+Control toggle in Control Center
+
+![A partial screenshot of the bottom of the Lock Screen on iPhone, highlighting that the Silent mode control is active on the right, with a symbol of a bell with a line drawn through it and red tint.](https://docs-assets.developer.apple.com/published/912ae3e318cf61d7146965079dc682cb/control-lock-screen%402x.png)
+
+Control toggle on the Lock Screen
+
+![A partial screenshot that displays the Dynamic Island at the top of the Home Screen on iPhone, showing that the Silent mode control is active with a red tinted symbol of a bell with a line drawn through it in the leading area and red tinted text that says Silent in the trailing area.](https://docs-assets.developer.apple.com/published/e336ce21634c50e782cfab47988eb576/control-dynamic-island%402x.png)
+
+Control toggle in the Dynamic Island  
+performed from the Action button
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/controls#Best-practices)
+
+**Offer controls for actions that provide the most benefit without having to launch your app.** For example, launching a Live Activity from a control creates an easy and seamless experience that informs someone about progress without having to navigate to your app to stay up to date. For guidance, see [Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities).
+
+**Update controls when someone interacts with them, when an action completes, or remotely with a push notification.** Update the contents of a control to accurately reflect the state and show if an action is still in progress.
+
+**Choose a descriptive symbol that suggests the behavior of the control.** Depending on where a person adds a control, it may not display the title and value, so the symbol needs to convey enough information about the control’s action. For control toggles, provide a symbol for both the on and off states. For example, use the SF Symbols `door.garage.open` and `door.garage.closed` to represent a control that opens and closes a garage door. For guidance, see [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols).
+
+**Use symbol animations to highlight state changes.** For control toggles, animate the transition between both on and off states. For control buttons with actions that have a duration, animate indefinitely while the action performs and stop animating when the action is complete. For developer guidance, see [Symbols](https://developer.apple.com/documentation/Symbols) and [`SymbolEffect`](https://developer.apple.com/documentation/Symbols/SymbolEffect).
+
+**Select a tint color that works with your app’s brand.** The system applies this tint color to a control toggle’s symbol in its on state. When a person performs the action of a control from the Action button, the system also uses this tint color to display the value and symbol in the Dynamic Island. For guidance, see [Branding](https://developer.apple.com/design/human-interface-guidelines/branding).
+
+![An inactive control toggle with a light bulb symbol that isn't tinted.](https://docs-assets.developer.apple.com/published/858a6c878e81223350b2c6175e7edc8d/control-lightbulb-not-tinted%402x.png)Nontinted control toggle in the off state
+
+![An active control toggle with a light bulb symbol that's tinted yellow.](https://docs-assets.developer.apple.com/published/6beab4a3187d3a10493645eaf5447811/control-lightbulb-tinted%402x.png)Tinted control toggle in the on state
+
+**Help people provide additional information the system needs to perform an action.** A person may need to configure a control to perform a desired action — for example, select a specific light in a house to turn on and off. If a control requires configuration, prompt people to complete this step when they first add it. People can reconfigure the control at any time. For developer guidance, see [`promptsForUserConfiguration()`](https://developer.apple.com/documentation/SwiftUI/ControlWidgetConfiguration/promptsForUserConfiguration\(\)).
+
+![A representation of a control with the ability to set an option to a value a person chooses.](https://docs-assets.developer.apple.com/published/2862099d2344c5c6576a3c4503b0c0b4/control-configuration-options%402x.png)
+
+**Provide hint text for the Action button.** When a person presses the Action button, the system displays hint text to help them understand what happens when they press and hold. When someone presses and holds the Action button, the system performs the action configured to it. Use verbs to construct the hint text. For developer guidance, see [`controlWidgetActionHint(_:)`](https://developer.apple.com/documentation/SwiftUI/View/controlWidgetActionHint\(_:\)-5yoyh).
+
+![A partial screenshot of the Home Screen on iPhone that displays hint text for the Action button. The hint text is Hold for Silent.](https://docs-assets.developer.apple.com/published/530aa049e2d419ed4af0e3e4a0fb812e/controls-action-button-coaching-text-on%402x.png)
+
+![A partial screenshot of the Home Screen on iPhone that displays hint text for the Action button. The hint text is Hold for Ring.](https://docs-assets.developer.apple.com/published/8058fe453e9c21c3654f7917f533a70a/controls-action-button-coaching-text-off%402x.png)
+
+**If your control title or value can vary, include a placeholder.** Placeholder information tells people what your control does when the title and value are situational. The system displays this information when someone brings up the controls gallery in Control Center or the Lock Screen and chooses your control, or before they assign it to the Action button.
+
+**Hide sensitive information when the device is locked.** When the device is locked, consider having the system redact the title and value to hide personal or security-related information. Specify if the system needs to redact the symbol state as well. If specified, the system redacts the title and value, and displays the symbol in its off state.
+
+![A medium-size control toggle displaying a symbol of a light bulb, a title, and value text.](https://docs-assets.developer.apple.com/published/3239b45e3faff12f7e0c8faad57ac4da/control-regular-text%402x.png)Control toggle with no information hidden
+
+![A medium-size control toggle with redacted text.](https://docs-assets.developer.apple.com/published/60fdc68e4ffd056e2ced9b7c49ed6730/control-redacted-text%402x.png)Control toggle with information hidden on a locked device
+
+**Require authentication for actions that affect security.** For example, require people to unlock their device to access controls to lock or unlock the door to their house or start their car. For developer guidance, see [`IntentAuthenticationPolicy`](https://developer.apple.com/documentation/AppIntents/IntentAuthenticationPolicy).
+
+## [Camera experiences on a locked device](https://developer.apple.com/design/human-interface-guidelines/controls#Camera-experiences-on-a-locked-device)
+
+If your app supports camera capture, starting with iOS 18 you can create a control that launches directly to your app’s camera experience while the device is locked. For any task beyond capture, a person must authenticate and unlock their device to complete the task in your app. For developer guidance, see [LockedCameraCapture](https://developer.apple.com/documentation/LockedCameraCapture).
+
+**Use the same camera UI in your app and your camera experience.** Sharing UI leverages people’s familiarity with the app. By using the same UI, the transition to the app is seamless when someone captures content and taps a button to perform additional tasks, such as posting to a social network or editing a photo.
+
+**Provide instructions for adding the control.** Help people understand how to add the control that launches this camera experience.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/controls#Platform-considerations)
+
+ _No additional considerations for iOS or iPadOS. Not supported in macOS, watchOS, tvOS, or visionOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/controls#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/controls#Related)
+
+[Widgets](https://developer.apple.com/design/human-interface-guidelines/widgets)
+
+[Action button](https://developer.apple.com/design/human-interface-guidelines/action-button)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/controls#Developer-documentation)
+
+[LockedCameraCapture](https://developer.apple.com/documentation/LockedCameraCapture)
+
+[WidgetKit](https://developer.apple.com/documentation/WidgetKit)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/controls#Change-log)
+
+Date| Changes  
+---|---  
+June 10, 2024| New page.  
+  

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

@@ -0,0 +1,74 @@
+---
+title: "Gauges | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/gauges
+
+# Gauges
+
+A gauge displays a specific numerical value within a range of values.
+
+![A stylized representation of a circular numeric gauge above a linear percentage gauge. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/f32c347212ea5d73bc63f86d1a866225/components-gauges-intro%402x.png)
+
+In addition to indicating the current value in a range, a gauge can provide more context about the range itself. For example, a temperature gauge can use text to identify the highest and lowest temperatures in the range and display a spectrum of colors that visually reinforce the changing values.
+
+## [Anatomy](https://developer.apple.com/design/human-interface-guidelines/gauges#Anatomy)
+
+A gauge uses a circular or linear path to represent a range of values, mapping the current value to a specific point on the path. A standard gauge displays an indicator that shows the current value’s location; a gauge that uses the capacity style displays a fill that stops at the value’s location on the path.
+
+Circular and linear gauges in both standard and capacity styles are also available in a variant that’s visually similar to watchOS complications. This variant — called accessory — works well in iOS Lock Screen widgets and anywhere you want to echo the appearance of complications.
+
+Note
+
+In addition to gauges, macOS also supports level indicators, some of which have visual styles that are similar to gauges. For guidance, see [macOS](https://developer.apple.com/design/human-interface-guidelines/gauges#macOS).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/gauges#Best-practices)
+
+**Write succinct labels that describe the current value and both endpoints of the range.** Although not every gauge style displays all labels, VoiceOver reads the visible labels to help people understand the gauge without seeing the screen.
+
+**Consider filling the path with a gradient to help communicate the purpose of the gauge.** For example, a temperature gauge might use colors that range from red to blue to represent temperatures that range from hot to cold.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/gauges#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, visionOS, or watchOS. Not supported in tvOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/gauges#macOS)
+
+In addition to supporting gauges, macOS also defines a level indicator that displays a specific numerical value within a range. You can configure a level indicator to convey capacity, rating, or — rarely — relevance.
+
+The capacity style can depict discrete or continuous values.
+
+![An image of a continuous capacity indicator that uses the default green fill to indicate an amount of about two-thirds of the total capacity.](https://docs-assets.developer.apple.com/published/8d1f4b040b7736a1ba832b93a7dc3bfb/indicators-continuous%402x.png)
+
+**Continuous.** A horizontal translucent track that fills with a solid bar to indicate the current value.
+
+![An image of a discrete capacity indicator that uses the default green fill to indicate an amount of three-quarters of the total capacity.](https://docs-assets.developer.apple.com/published/f148e7934177391449aa61cc97ffea49/indicators-discrete%402x.png)
+
+**Discrete.** A horizontal row of separate, equally sized, rectangular segments. The number of segments matches the total capacity, and the segments fill completely — never partially — with color to indicate the current value.
+
+**Consider using the continuous style for large ranges.** A large value range can make the segments of a discrete capacity indicator too small to be useful.
+
+**Consider changing the fill color to inform people about significant parts of the range.** By default, the fill color for both capacity indicator styles is green. If it makes sense in your app, you can change the fill color when the current value reaches certain levels, such as very low, very high, or just past the middle. You can change the fill color of the entire indicator or you can use the tiered state to show a sequence of several colors in one indicator, as shown below.
+
+![An image of a continuous capacity indicator in which the leftmost one-eigth is red, the next three-eighths are yellow, the next one-fourth is green, and the last one-fourth is unfilled.](https://docs-assets.developer.apple.com/published/6d84b116ed12ffcabc2a36fb8f63e31e/indicators-continuous-tiered%402x.png)Tiered level appearance
+
+For guidance using the rating style to help people rank something, see [Rating indicators](https://developer.apple.com/design/human-interface-guidelines/rating-indicators).
+
+Although rarely used, the relevance style can communicate relevancy using a shaded horizontal bar. For example, a relevance indicator might appear in a list of search results, helping people visualize the relevancy of the results when sorting or comparing multiple items.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/gauges#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/gauges#Related)
+
+[Ratings and reviews](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/gauges#Developer-documentation)
+
+[`Gauge`](https://developer.apple.com/documentation/SwiftUI/Gauge) — SwiftUI
+
+[`NSLevelIndicator`](https://developer.apple.com/documentation/AppKit/NSLevelIndicator) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/gauges#Change-log)
+
+Date| Changes  
+---|---  
+September 23, 2022| New page.  
+  

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

@@ -0,0 +1,92 @@
+---
+title: "Labels | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/labels
+
+# Labels
+
+A label is a static piece of text that people can read and often copy, but not edit.
+
+![A stylized representation of a text label. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/b428963465f223dd1fdd01779043810c/components-label-intro%402x.png)
+
+Labels display text throughout the interface, in buttons, menu items, and views, helping people understand the current context and what they can do next.
+
+The term _label_ refers to uneditable text that can appear in various places. For example:
+
+  * Within a button, a label generally conveys what the button does, such as Edit, Cancel, or Send.
+
+  * Within many lists, a label can describe each item, often accompanied by a symbol or an image.
+
+  * Within a view, a label might provide additional context by introducing a control or describing a common action or task that people can perform in the view.
+
+
+
+
+Developer note
+
+To display uneditable text, SwiftUI defines two components: [`Label`](https://developer.apple.com/documentation/SwiftUI/Label) and [`Text`](https://developer.apple.com/documentation/SwiftUI/Text).
+
+The guidance below can help you use a label to display text. In some cases, guidance for specific components — such as [action buttons](https://developer.apple.com/design/human-interface-guidelines/buttons), [menus](https://developer.apple.com/design/human-interface-guidelines/menus), and [lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) — includes additional recommendations for using text.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/labels#Best-practices)
+
+**Use a label to display a small amount of text that people don’t need to edit.** If you need to let people edit a small amount of text, use a [text field](https://developer.apple.com/design/human-interface-guidelines/text-fields). If you need to display a large amount of text, and optionally let people edit it, use a [text view](https://developer.apple.com/design/human-interface-guidelines/text-views).
+
+**Prefer system fonts.** A label can display plain or styled text, and it supports Dynamic Type (where available) by default. If you adjust the style of a label or use custom fonts, make sure the text remains legible.
+
+**Use system-provided label colors to communicate relative importance.** The system defines four label colors that vary in appearance to help you give text different levels of visual importance. For additional guidance, see [Color](https://developer.apple.com/design/human-interface-guidelines/color).
+
+System color| Example usage| iOS, iPadOS, tvOS, visionOS| macOS  
+---|---|---|---  
+Label| Primary information| [`label`](https://developer.apple.com/documentation/UIKit/UIColor/label)| [`labelColor`](https://developer.apple.com/documentation/AppKit/NSColor/labelColor)  
+Secondary label| A subheading or supplemental text| [`secondaryLabel`](https://developer.apple.com/documentation/UIKit/UIColor/secondaryLabel)| [`secondaryLabelColor`](https://developer.apple.com/documentation/AppKit/NSColor/secondaryLabelColor)  
+Tertiary label| Text that describes an unavailable item or behavior| [`tertiaryLabel`](https://developer.apple.com/documentation/UIKit/UIColor/tertiaryLabel)| [`tertiaryLabelColor`](https://developer.apple.com/documentation/AppKit/NSColor/tertiaryLabelColor)  
+Quaternary label| Watermark text| [`quaternaryLabel`](https://developer.apple.com/documentation/UIKit/UIColor/quaternaryLabel)| [`quaternaryLabelColor`](https://developer.apple.com/documentation/AppKit/NSColor/quaternaryLabelColor)  
+  
+**Make useful label text selectable.** If a label contains useful information — like an error message, a location, or an IP address — consider letting people select and copy it for pasting elsewhere.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/labels#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, tvOS, or visionOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/labels#macOS)
+
+Developer note
+
+To display uneditable text in a label, use the [`isEditable`](https://developer.apple.com/documentation/AppKit/NSTextField/isEditable) property of [`NSTextField`](https://developer.apple.com/documentation/AppKit/NSTextField).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/labels#watchOS)
+
+Date and time text components (shown below on the left) display the current date, the current time, or a combination of both. You can configure a date text component to use a variety of formats, calendars, and time zones. A countdown timer text component (shown below on the right) displays a precise countdown or count-up timer. You can configure a timer text component to display its count value in a variety of formats.
+
+![An illustration of date and time text components on Apple Watch, with the date aligned to the leading edge and the time aligned to the trailing edge.](https://docs-assets.developer.apple.com/published/3cedf27f398b6683c78d37a325f26c33/labels-date-time-text-component%402x.png)Date and time labels
+
+![An illustration of a countdown timer text component on Apple Watch, with the time value at the center.](https://docs-assets.developer.apple.com/published/bc3014364c7bc508ff68d21d79c15441/labels-countdown-timer-text-component%402x.png)Timer label
+
+When you use the system-provided date and timer text components, watchOS automatically adjusts the label’s presentation to fit the available space. The system also updates the content without further input from your app.
+
+Consider using date and timer components in complications. For design guidance, see [Complications](https://developer.apple.com/design/human-interface-guidelines/components/system-experiences/complications); for developer guidance, see [`Text`](https://developer.apple.com/documentation/SwiftUI/Text).
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/labels#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/labels#Related)
+
+[Text fields](https://developer.apple.com/design/human-interface-guidelines/text-fields)
+
+[Text views](https://developer.apple.com/design/human-interface-guidelines/text-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/labels#Developer-documentation)
+
+[`Label`](https://developer.apple.com/documentation/SwiftUI/Label) — SwiftUI
+
+[`Text`](https://developer.apple.com/documentation/SwiftUI/Text) — SwiftUI
+
+[`UILabel`](https://developer.apple.com/documentation/UIKit/UILabel) — UIKit
+
+[`NSTextField`](https://developer.apple.com/documentation/AppKit/NSTextField) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/labels#Change-log)
+
+Date| Changes  
+---|---  
+June 5, 2023| Updated guidance to reflect changes in watchOS 10.  
+  

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

@@ -0,0 +1,128 @@
+---
+title: "Pickers | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/pickers
+
+# Pickers
+
+A picker displays one or more scrollable lists of distinct values that people can choose from.
+
+![A stylized representation of a selected item in a scrollable list. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/56b152d613ef1fc1424549eaa95a23d6/components-pickers-intro%402x.png)
+
+The system provides several styles of pickers, each of which offers different types of selectable values and has a different appearance. The exact values shown in a picker, and their order, depend on the device language.
+
+Pickers help people enter information by letting them choose single or multipart values. Date pickers specifically offer additional ways to choose values, like selecting a day in a calendar view or entering dates and times using a numeric keypad.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/pickers#Best-practices)
+
+**Consider using a picker to offer medium-to-long lists of items.** If you need to display a fairly short list of choices, consider using a [pull-down button](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons) instead of a picker. Although a picker makes it easy to scroll quickly through many items, it may add too much visual weight to a short list of items. On the other hand, if you need to present a very large set of items, consider using a [list or table](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables). Lists and tables can adjust in height, and tables can include an index, which makes it much faster to target a section of the list.
+
+**Use predictable and logically ordered values.** Before people interact with a picker, many of its values can be hidden. It’s best when people can predict what the hidden values are, such as with an alphabetized list of countries, so they can move through the items quickly.
+
+**Avoid switching views to show a picker.** A picker works well when displayed in context, below or in proximity to the field people are editing. A picker typically appears at the bottom of a window or in a popover.
+
+**Consider providing less granularity when specifying minutes in a date picker.** By default, a minute list includes 60 values (0 to 59). You can optionally increase the minute interval as long as it divides evenly into 60. For example, you might want quarter-hour intervals (0, 15, 30, and 45).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/pickers#Platform-considerations)
+
+ _No additional considerations for visionOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/pickers#iOS-iPadOS)
+
+A date picker is an efficient interface for selecting a specific date, time, or both, using touch, a keyboard, or a pointing device. You can display a date picker in one of the following styles:
+
+  * Compact — A button that displays editable date and time content in a modal view.
+
+  * Inline — For time only, a button that displays wheels of values; for dates and times, an inline calendar view.
+
+  * Wheels — A set of scrolling wheels that also supports data entry through built-in or external keyboards.
+
+  * Automatic — A system-determined style based on the current platform and date picker mode.
+
+
+
+
+A date picker has four modes, each of which presents a different set of selectable values.
+
+  * Date — Displays months, days of the month, and years.
+
+  * Time — Displays hours, minutes, and (optionally) an AM/PM designation.
+
+  * Date and time — Displays dates, hours, minutes, and (optionally) an AM/PM designation.
+
+  * Countdown timer — Displays hours and minutes, up to a maximum of 23 hours and 59 minutes. This mode isn’t available in the inline or compact styles.
+
+
+
+
+The exact values shown in a date picker, and their order, depend on the device location.
+
+Here are several examples of date pickers showing different combinations of style and mode.
+
+  * Compact 
+  * Inline 
+  * Wheels 
+
+
+
+![An illustration of a compact date picker, with a single inline row showing the currently selected date. The picker opens as a popover extending down from the row, and includes a full calendar month for choosing the date.](https://docs-assets.developer.apple.com/published/65d6693bf614da95dde6a82006037c86/pickers-date-picker-compact-expanded%402x.png)In a compact layout, a picker opens as a popover over your content.
+
+![An illustration of an inline date picker, titled 'Date'. A toggle at the top is switched on, and a calendar month for choosing the date appears below the title and toggle.](https://docs-assets.developer.apple.com/published/053773055a1630d38d3baa6ec6147f5d/pickers-date-picker-inline-expanded%402x.png)In an inline layout, a picker opens inline with your content.
+
+![An illustration of an inline time picker, titled 'Time'. The currently selected time appears in the title row, and three vertical wheels appear below the title row for choosing the hour, minute, and AM or PM value.](https://docs-assets.developer.apple.com/published/4474f286571f0a7b875bbd940f39bb78/pickers-time-picker-inline-wheel%402x.png)Another example of an inline picker uses wheels to choose values for date and time.
+
+**Use a compact date picker when space is constrained.** The compact style displays a button that shows the current value in your app’s accent color. When people tap the button, the date picker opens a modal view, providing access to a familiar calendar-style editor and time picker. Within the modal view, people can make multiple edits to dates and times before tapping outside the view to confirm their choices.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/pickers#macOS)
+
+**Choose a date picker style that suits your app.** There are two styles of date pickers in macOS: textual and graphical. The textual style is useful when you’re working with limited space and you expect people to make specific date and time selections. The graphical style is useful when you want to give people the option of browsing through days in a calendar or selecting a range of dates, or when the look of a clock face is appropriate for your app.
+
+For developer guidance, see [`NSDatePicker`](https://developer.apple.com/documentation/AppKit/NSDatePicker).
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/pickers#tvOS)
+
+Pickers are available in tvOS with SwiftUI. For developer guidance, see [`Picker`](https://developer.apple.com/documentation/SwiftUI/Picker).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/pickers#watchOS)
+
+Pickers display lists of items that people navigate using the Digital Crown, which helps people manage selections in a precise and engaging way.
+
+A picker can display a list of items using the wheels style. watchOS can also display date and time pickers using the wheels style. For developer guidance, see [`Picker`](https://developer.apple.com/documentation/SwiftUI/Picker) and [`DatePicker`](https://developer.apple.com/documentation/SwiftUI/DatePicker).
+
+![An illustration representing a screen containing a picker view on Apple Watch, showing three items in a list. The center item is highlighted.](https://docs-assets.developer.apple.com/published/00d1eeb88cc503430767c2318605a71d/pickers-wheel-watch%402x.png)
+
+![An illustration representing a screen containing a date picker on Apple Watch, with the day highlighted.](https://docs-assets.developer.apple.com/published/30053c6f5cb2c0246e5ebecbd8ad70c3/pickers-date-watch%402x.png)
+
+![An illustration representing a screen containing a time picker on Apple Watch, with the minutes highlighted.](https://docs-assets.developer.apple.com/published/842ba89f2c3fdb2894949dee31bf8849/pickers-time-watch%402x.png)
+
+You can configure a picker to display an outline, caption, and scrolling indicator.
+
+For longer lists, the navigation link displays the picker as a button. When someone taps the button, the system shows the list of options. The person can also scrub through the options using the Digital Crown without tapping the button. For developer guidance, see [`navigationLink`](https://developer.apple.com/documentation/SwiftUI/PickerStyle/navigationLink).
+
+![An illustration representing a screen that contains a picker button on Apple Watch. The button’s text denotes that the second item is selected.](https://docs-assets.developer.apple.com/published/657d90a59d600e7eee70effde6784e45/pickers-navigation-button-watch%402x.png)
+
+![An illustration representing a screen showing a list of items on Apple Watch. The second item in the list is selected.](https://docs-assets.developer.apple.com/published/1e533809fb6fc291a53fd12ff0ec41f4/pickers-navigation-list-watch%402x.png)
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/pickers#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/pickers#Related)
+
+[Pull-down buttons](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons)
+
+[Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/pickers#Developer-documentation)
+
+[`Picker`](https://developer.apple.com/documentation/SwiftUI/Picker) — SwiftUI
+
+[`UIDatePicker`](https://developer.apple.com/documentation/UIKit/UIDatePicker) — UIKit
+
+[`UIPickerView`](https://developer.apple.com/documentation/UIKit/UIPickerView) — UIKit
+
+[`NSDatePicker`](https://developer.apple.com/documentation/AppKit/NSDatePicker) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/pickers#Change-log)
+
+Date| Changes  
+---|---  
+June 5, 2023| Updated guidance for using pickers in watchOS.  
+  

package/skills/hig-components-controls/references/rating-indicators.md

@@ -0,0 +1,38 @@
+---
+title: "Rating indicators | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/rating-indicators
+
+# Rating indicators
+
+A rating indicator uses a series of horizontally arranged graphical symbols — by default, stars — to communicate a ranking level.
+
+![A stylized representation of a rating indicator denoting a ranking of three out of five stars. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/aacce03e9d1c173b00080802bc79ff5d/components-rating-indicators-intro%402x.png)
+
+A rating indicator doesn’t display partial symbols; it rounds the value to display complete symbols only. Within a rating indicator, symbols are always the same distance apart and don’t expand or shrink to fit the component’s width.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Best-practices)
+
+**Make it easy to change rankings.** When presenting a list of ranked items, let people adjust the rank of individual items inline without navigating to a separate editing screen.
+
+**If you replace the star with a custom symbol, make sure that its purpose is clear.** The star is a very recognizable ranking symbol, and people may not associate other symbols with a rating scale.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Platform-considerations)
+
+ _No additional considerations for macOS. Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Related)
+
+[Ratings and reviews](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Developer-documentation)
+
+[`NSLevelIndicator.Style.rating`](https://developer.apple.com/documentation/AppKit/NSLevelIndicator/Style/rating) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/rating-indicators#Change-log)
+
+Date| Changes  
+---|---  
+September 23, 2022| New page.  
+