bps-kit 1.0.1 → 1.0.3

package/templates/vault/hig-components-controls/references/labels.md

@@ -1,92 +0,0 @@
----
-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/templates/vault/hig-components-controls/references/pickers.md

@@ -1,128 +0,0 @@
----
-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/templates/vault/hig-components-controls/references/rating-indicators.md

@@ -1,38 +0,0 @@
----
-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.  
-  

package/templates/vault/hig-components-controls/references/segmented-controls.md

@@ -1,94 +0,0 @@
----
-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/templates/vault/hig-components-controls/references/sliders.md

@@ -1,92 +0,0 @@
----
-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/templates/vault/hig-components-controls/references/steppers.md

@@ -1,40 +0,0 @@
----
-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/templates/vault/hig-components-controls/references/text-fields.md

@@ -1,88 +0,0 @@
----
-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.  
-