bps-kit 1.0.1 → 1.0.3

package/templates/vault/hig-components-layout/references/split-views.md

@@ -1,110 +0,0 @@
----
-title: "Split views | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/split-views
-
-# Split views
-
-A split view manages the presentation of multiple adjacent panes of content, each of which can contain a variety of components, including tables, collections, images, and custom views.
-
-![A stylized representation of a window consisting of three areas: a sidebar, a canvas, and an inspector. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/68c529d6dd40b4b46f1862f1cdbadec4/components-split-view-intro%402x.png)
-
-Typically, you use a split view to show multiple levels of your app’s hierarchy at once and support navigation between them. In this scenario, selecting an item in the view’s primary pane displays the item’s contents in the secondary pane. Similarly, a split view can display a tertiary pane if items in the secondary pane contain additional content.
-
-It’s common to use a split view to display a [sidebar](https://developer.apple.com/design/human-interface-guidelines/sidebars) for navigation, where the leading pane lists the top-level items or collections in an app, and the secondary and optional tertiary panes can present child collections and item details. Rarely, you might also use a split view to provide groups of functionality that supplement the primary view — for example, Keynote in macOS uses split view panes to present the slide navigator, the presenter notes, and the inspector pane in areas that surround the main slide canvas.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/split-views#Best-practices)
-
-**To support navigation, persistently highlight the current selection in each pane that leads to the detail view.** The selected appearance clarifies the relationship between the content in various panes and helps people stay oriented.
-
-**Consider letting people drag and drop content between panes.** Because a split view provides access to multiple levels of hierarchy, people can conveniently move content from one part of your app to another by dragging items to different panes. For guidance, see [Drag and drop](https://developer.apple.com/design/human-interface-guidelines/drag-and-drop).
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/split-views#Platform-considerations)
-
-### [iOS](https://developer.apple.com/design/human-interface-guidelines/split-views#iOS)
-
-**Prefer using a split view in a regular — not a compact — environment.** A split view needs horizontal space in which to display multiple panes. In a compact environment, such as iPhone in portrait orientation, it’s difficult to display multiple panes without wrapping or truncating the content, making it less legible and harder to interact with.
-
-### [iPadOS](https://developer.apple.com/design/human-interface-guidelines/split-views#iPadOS)
-
-In iPadOS, a split view can include either two vertical panes, like Mail, or three vertical panes, like Keynote.
-
-**Account for narrow, compact, and intermediate window widths.** Since iPad windows are fluidly resizable, it’s important to consider the design of a split view layout at multiple widths. In particular, ensure that it’s possible to navigate between the various panes in a logical way. For guidance, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout). For developer guidance, see [`NavigationSplitView`](https://developer.apple.com/documentation/SwiftUI/NavigationSplitView) and [`UISplitViewController`](https://developer.apple.com/documentation/UIKit/UISplitViewController).
-
-### [macOS](https://developer.apple.com/design/human-interface-guidelines/split-views#macOS)
-
-In macOS, you can arrange the panes of a split view vertically, horizontally, or both. A split view includes dividers between panes that can support dragging to resize them. For developer guidance, see [`VSplitView`](https://developer.apple.com/documentation/SwiftUI/VSplitView) and [`HSplitView`](https://developer.apple.com/documentation/SwiftUI/HSplitView).
-
-  * Vertical 
-  * Horizontal 
-  * Multiple 
-
-
-
-![An illustration of a laptop screen that shows two panes stacked vertically.](https://docs-assets.developer.apple.com/published/8c23f101a012db47a8e2350e50432617/vertical-split-view%402x.png)
-
-![An illustration of a laptop screen that shows two panes arranged side by side, with a narrower pane on the left and a wider pane on the right.](https://docs-assets.developer.apple.com/published/713be8f9e61a9578b26087ad71ca6b23/horizontal-split-view%402x.png)
-
-![An illustration of a laptop screen divided into three panes, split both vertically and horizontally.](https://docs-assets.developer.apple.com/published/3e315fbb8f8ade8b2d3d4f105f8c4482/multiple-split-view%402x.png)
-
-**Set reasonable defaults for minimum and maximum pane sizes.** If people can resize the panes in your app’s split view, make sure to use sizes that keep the divider visible. If a pane gets too small, the divider can seem to disappear, becoming difficult to use.
-
-**Consider letting people hide a pane when it makes sense.** If your app includes an editing area, for example, consider letting people hide other panes to reduce distractions or allow more room for editing — in Keynote, people can hide the navigator and presenter notes panes when they want to edit slide content.
-
-**Provide multiple ways to reveal hidden panes.** For example, you might provide a toolbar button or a menu command — including a keyboard shortcut — that people can use to restore a hidden pane.
-
-**Prefer the thin divider style.** The thin divider measures one point in width, giving you maximum space for content while remaining easy for people to use. Avoid using thicker divider styles unless you have a specific need. For example, if both sides of a divider present table rows that use strong linear elements that might make a thin divider hard to distinguish, it might work to use a thicker divider. For developer guidance, see [`NSSplitView.DividerStyle`](https://developer.apple.com/documentation/AppKit/NSSplitView/DividerStyle-swift.enum).
-
-### [tvOS](https://developer.apple.com/design/human-interface-guidelines/split-views#tvOS)
-
-In tvOS, a split view can work well to help people filter content. When people choose a filter category in the primary pane, your app can display the results in the secondary pane.
-
-**Choose a split view layout that keeps the panes looking balanced.** By default, a split view devotes a third of the screen width to the primary pane and two-thirds to the secondary pane, but you can also specify a half-and-half layout.
-
-**Display a single title above a split view, helping people understand the content as a whole.** People already know how to use a split view to navigate and filter content; they don’t need titles that describe what each pane contains.
-
-**Choose the title’s alignment based on the type of content the secondary pane contains.** Specifically, when the secondary pane contains a content collection, consider centering the title in the window. In contrast, if the secondary pane contains a single main view of important content, consider placing the title above the primary view to give the content more room.
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/split-views#visionOS)
-
-**To display supplementary information, prefer a split view instead of a new window.** A split view gives people convenient access to more information without leaving the current context, whereas a new window may confuse people who are trying to navigate or reposition content. Opening more windows also requires you to carefully manage the relationship between views in your app or game. If you need to request a small amount of information or present a simple task that someone must complete before returning to their main task, use a [sheet](https://developer.apple.com/design/human-interface-guidelines/sheets).
-
-### [watchOS](https://developer.apple.com/design/human-interface-guidelines/split-views#watchOS)
-
-In watchOS, the split view displays either the list view or a detail view as a full-screen view.
-
-**Automatically display the most relevant detail view.** When your app launches, show people the most pertinent information. For example, display information relevant to their location, the time, or their recent actions.
-
-**If your app displays multiple detail pages, place the detail views in a vertical[tab view](https://developer.apple.com/design/human-interface-guidelines/tab-views).** People can then use the Digital Crown to scroll between the detail view’s tabs. watchOS also displays a page indicator next to the Digital Crown, indicating the number of tabs and the currently selected tab.
-
-![A screenshot showing a detail view with a vertical tab on Apple Watch. The page indicator next to the Digital Crown shows that the fifth tab is currently selected.](https://docs-assets.developer.apple.com/published/3f36258648d54880e800568e88b5076b/split-view-watch-vertical-tab%402x.png)
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/split-views#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/split-views#Related)
-
-[Sidebars](https://developer.apple.com/design/human-interface-guidelines/sidebars)
-
-[Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars)
-
-[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/split-views#Developer-documentation)
-
-[`NavigationSplitView`](https://developer.apple.com/documentation/SwiftUI/NavigationSplitView) — SwiftUI
-
-[`UISplitViewController`](https://developer.apple.com/documentation/UIKit/UISplitViewController) — UIKit
-
-[`NSSplitViewController`](https://developer.apple.com/documentation/AppKit/NSSplitViewController) — AppKit
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/split-views#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/A8CAF870-197F-4982-83D8-56513E5D7D0B/10000_wide_250x141_1x.jpg) Make your UIKit app more flexible ](https://developer.apple.com/videos/play/wwdc2025/282)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/split-views#Change-log)
-
-Date| Changes  
----|---  
-June 9, 2025| Added iOS and iPadOS platform considerations.  
-December 5, 2023| Added guidance for split views in visionOS.  
-June 5, 2023| Added guidance for split views in watchOS.  
-  

package/templates/vault/hig-components-layout/references/tab-bars.md

@@ -1,173 +0,0 @@
----
-title: "Tab bars | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/tab-bars
-
-# Tab bars
-
-A tab bar lets people navigate between top-level sections of your app.
-
-![A stylized representation of a tab bar containing four placeholder icons with names. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/8737d6baf5cdb223521eb4dbe3cb45e5/components-tab-bar-intro%402x.png)
-
-Tab bars help people understand the different types of information or functionality that an app provides. They also let people quickly switch between sections of the view while preserving the current navigation state within each section.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Best-practices)
-
-**Use a tab bar to support navigation, not to provide actions.** A tab bar lets people navigate among different sections of an app, like the Alarm, Stopwatch, and Timer tabs in the Clock app. If you need to provide controls that act on elements in the current view, use a [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars) instead.
-
-**Make sure the tab bar is visible when people navigate to different sections of your app.** If you hide the tab bar, people can forget which area of the app they’re in. The exception is when a modal view covers the tab bar, because a modal is temporary and self-contained.
-
-**Use the appropriate number of tabs required to help people navigate your app.** As a representation of your app’s hierarchy, it’s important to weigh the complexity of additional tabs against the need for people to frequently access each section; keep in mind that it’s generally easier to navigate among fewer tabs. Where available, consider a sidebar or a tab bar that adapts to a sidebar as an alternative for an app with a complex information structure.
-
-**Avoid overflow tabs.** Depending on device size and orientation, the number of visible tabs can be smaller than the total number of tabs. If horizontal space limits the number of visible tabs, the trailing tab becomes a More tab in iOS and iPadOS, revealing the remaining items in a separate list. The More tab makes it harder for people to reach and notice content on tabs that are hidden, so limit scenarios in your app where this can happen.
-
-**Don’t disable or hide tab bar buttons, even when their content is unavailable.** Having tab bar buttons available in some cases but not others makes your app’s interface appear unstable and unpredictable. If a section is empty, explain why its content is unavailable.
-
-**Include tab labels to help with navigation.** A tab label appears beneath or beside a tab bar icon, and can aid navigation by clearly describing the type of content or functionality the tab contains. Use single words whenever possible.
-
-**Consider using SF Symbols to provide familiar, scalable tab bar icons.** When you use [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols), tab bar icons automatically adapt to different contexts. For example, the tab bar can be regular or compact, depending on the device and orientation. Tab bar icons appear above tab labels in compact views, whereas in regular views, the icons and labels appear side by side. Prefer filled symbols or icons for consistency with the platform.
-
-![An illustration of two iPhone devices side by side. The first iPhone is in landscape orientation with a tab bar at the bottom of the screen, with tab bar icons on the leading edge of each tab and tab labels on the trailing edge. The second iPhone is in portrait orientation with a tab bar at the bottom of the screen, with tab bar icons above their respective tab labels.](https://docs-assets.developer.apple.com/published/6871e7b24b6da37f753c61deba02c8ab/tab-bar-landscape%402x.png)
-
-If you’re creating custom tab bar icons, see [Apple Design Resources](https://developer.apple.com/design/resources/) for tab bar icon dimensions.
-
-![A diagram of a tab bar, with callouts indicating the location of the tab bar icon and tab label.](https://docs-assets.developer.apple.com/published/eb47e442c964d54ed32f9324c71511d1/tab-bar-anatomy-callouts%402x.png)
-
-**Use a badge to indicate that critical information is available.** You can display a badge — a red oval containing white text and either a number or an exclamation point — on a tab to indicate that there’s new or updated information in the section that warrants a person’s attention. Reserve badges for critical information so you don’t dilute their impact and meaning. For guidance, see [Notifications](https://developer.apple.com/design/human-interface-guidelines/notifications).
-
-![An illustration of the bottom half of an iPhone in portrait orientation, with a tab bar at the bottom of the screen. Two of the tabs have red circular badges attached, indicating the presence of critical information.](https://docs-assets.developer.apple.com/published/29a93bc69eaa415e2e3d5440474a8d36/tab-bar-badges-iphone%402x.png)
-
-**Avoid applying a similar color to tab labels and content layer backgrounds.** If your app already has bright, colorful content in the content layer, prefer a monochromatic appearance for tab bars, or choose an accent color with sufficient visual differentiation. For more guidance, see [Liquid Glass color](https://developer.apple.com/design/human-interface-guidelines/color#Liquid-Glass-color).
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Platform-considerations)
-
- _No additional considerations for macOS. Not supported in watchOS._
-
-### [iOS](https://developer.apple.com/design/human-interface-guidelines/tab-bars#iOS)
-
-A tab bar floats above content at the bottom of the screen. Its items rest on a [Liquid Glass](https://developer.apple.com/design/human-interface-guidelines/materials#Liquid-Glass) background that allows content beneath to peek through.
-
-For tab bars with an attached accessory, like the MiniPlayer in Music, you can choose to minimize the tab bar and move the accessory inline with it when a person scrolls down. A person can exit the minimized state by tapping a tab or scrolling to the top of the view. For developer guidance, see [`TabBarMinimizeBehavior`](https://developer.apple.com/documentation/SwiftUI/TabBarMinimizeBehavior) and [`UITabBarController.MinimizeBehavior`](https://developer.apple.com/documentation/UIKit/UITabBarController/MinimizeBehavior).
-
-![An illustration of the bottom half of an iPhone in portrait orientation, with the Music app open. The MiniPlayer is open above the tab bar at the bottom of the screen.](https://docs-assets.developer.apple.com/published/1b8fb04a802aacd9c9f46ba7b16be080/tab-bar-with-accessory-expanded%402x.png)
-
-A tab bar with an attached accessory, expanded
-
-![An illustration of the bottom half of an iPhone in portrait orientation, with the Music app open. The tab bar is minimized into the currently open tab at the leading bottom corner of the screen, with the MiniPlayer at the bottom center, and the search tab in the trailing corner.](https://docs-assets.developer.apple.com/published/d074ff4013a38155a887ceeecf2417fa/tab-bar-with-accessory-collapsed%402x.png)
-
-A tab bar with an attached accessory, minimized
-
-A tab bar can include a distinct search item at the trailing end. For guidance, see [Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields).
-
-### [iPadOS](https://developer.apple.com/design/human-interface-guidelines/tab-bars#iPadOS)
-
-The system displays a tab bar near the top of the screen. You can choose to have the tab bar appear as a fixed element, or with a button that converts it to a sidebar. For developer guidance, see [`tabBarOnly`](https://developer.apple.com/documentation/SwiftUI/TabViewStyle/tabBarOnly) and [`sidebarAdaptable`](https://developer.apple.com/documentation/SwiftUI/TabViewStyle/sidebarAdaptable).
-
-  * Tab bar 
-  * Sidebar 
-
-
-
-![A screenshot showing the Music app on iPad with the tab bar near the top of the screen.](https://docs-assets.developer.apple.com/published/66af6b050f67a05a82c5df2acb99913a/ipad-tab-bar-music-app%402x.png)
-
-![A screenshot showing the Music app on iPad with the tab bar converted to a sidebar on the leading edge of the screen.](https://docs-assets.developer.apple.com/published/cb52cc194e4067efff244c3b991a02a4/ipad-sidebar-music-app%402x.png)
-
-Note
-
-To present a sidebar without the option to convert it to a tab bar, use a [navigation split view](https://developer.apple.com/documentation/swiftui/navigationsplitview) instead of a tab view. For guidance, see [Sidebars](https://developer.apple.com/design/human-interface-guidelines/sidebars).
-
-**Prefer a tab bar for navigation.** A tab bar provides access to the sections of your app that people use most. If your app is more complex, you can provide the option to convert the tab bar to a sidebar so people can access a wider set of navigation options.
-
-**Let people customize the tab bar.** In apps with a lot of sections that people might want to access, it can be useful to let people select items that they use frequently and add them to the tab bar, or remove items that they use less frequently. For example, in the Music app, a person can choose a favorite playlist to display in the tab bar. If you let people select their own tabs, aim for a default list of five or fewer to preserve continuity between compact and regular view sizes. For developer guidance, see [`TabViewCustomization`](https://developer.apple.com/documentation/SwiftUI/TabViewCustomization) and [`UITab.Placement`](https://developer.apple.com/documentation/UIKit/UITab/Placement).
-
-### [tvOS](https://developer.apple.com/design/human-interface-guidelines/tab-bars#tvOS)
-
-A tab bar is highly customizable. For example, you can:
-
-  * Specify a tint, color, or image for the tab bar background
-
-  * Choose a font for tab items, including a different font for the selected item
-
-  * Specify tints for selected and unselected items
-
-  * Add button icons, like settings and search
-
-
-
-
-By default, a tab bar is translucent, and only the selected tab is opaque. When people use the remote to focus on the tab bar, the selected tab includes a drop shadow that emphasizes its selected state. The height of a tab bar is 68 points, and its top edge is 46 points from the top of the screen; you can’t change either of these values.
-
-If there are more items than can fit in the tab bar, the system truncates the rightmost item by applying a fade effect that begins at the right side of the tab bar. If there are enough items to cause scrolling, the system also applies a truncating fade effect that starts from the left side.
-
-**Be aware of tab bar scrolling behaviors.** By default, people can scroll the tab bar offscreen when the current tab contains a single main view. You can see examples of this behavior in the Watch Now, Movies, TV Show, Sports, and Kids tabs in the TV app. The exception is when a screen contains a split view, such as the TV app’s Library tab or an app’s Settings screen. In this case, the tab bar remains pinned at the top of the view while people scroll the content within the primary and secondary panes of the split view. Regardless of a tab’s contents, focus always returns to the tab bar at the top of the page when people press Menu on the remote.
-
-**In a live-viewing app, organize tabs in a consistent way.** For the best experience, organize content in live-streaming apps with tabs in the following order:
-
-  * Live content
-
-  * Cloud DVR or other recorded content
-
-  * Other content
-
-
-
-
-For additional guidance, see [Live-viewing apps](https://developer.apple.com/design/human-interface-guidelines/live-viewing-apps).
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/tab-bars#visionOS)
-
-In visionOS, a tab bar is always vertical, floating in a position that’s fixed relative to the window’s leading side. When people look at a tab bar, it automatically expands; to open a specific tab, people look at the tab and tap. While a tab bar is expanded, it can temporarily obscure the content behind it.
-
-Video with custom controls. 
-
-Content description: A recording showing a closeup of a tab bar along the side of an app's window in visionOS. The tab bar includes only symbols. The currently selected tab receives the hover effect, showing that someone is looking at it, and the bar expands to display both symbols and labels. 
-
-Play 
-
-**Supply a symbol and a text label for each tab.** A tab’s symbol is always visible in the tab bar. When people look at the tab bar, the system reveals tab labels, too. Even though the tab bar expands, you need to keep tab labels short so people can read them at a glance.
-
-![A screenshot showing a collapsed tab bar containing only symbols.](https://docs-assets.developer.apple.com/published/60282ea47a438f5b2bd84705212b44e4/visionos-tab-bar-collapsed%402x.png)Collapsed
-
-![A screenshot showing an expanded tab bar containing both symbols and labels.](https://docs-assets.developer.apple.com/published/df1a14ce3d5e2743bfdfb0fea47fc340/visionos-tab-bar-expanded%402x.png)Expanded
-
-**If it makes sense in your app, consider using a sidebar within a tab.** If your app’s hierarchy is deep, you might want to use a [sidebar](https://developer.apple.com/design/human-interface-guidelines/sidebars) to support secondary navigation within a tab. If you do this, be sure to prevent selections in the sidebar from changing which tab is currently open.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Related)
-
-[Tab views](https://developer.apple.com/design/human-interface-guidelines/tab-views)
-
-[Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars)
-
-[Sidebars](https://developer.apple.com/design/human-interface-guidelines/sidebars)
-
-[Materials](https://developer.apple.com/design/human-interface-guidelines/materials)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Developer-documentation)
-
-[`TabView`](https://developer.apple.com/documentation/SwiftUI/TabView) — SwiftUI
-
-[`TabViewBottomAccessoryPlacement`](https://developer.apple.com/documentation/SwiftUI/TabViewBottomAccessoryPlacement) — SwiftUI
-
-[Enhancing your app’s content with tab navigation](https://developer.apple.com/documentation/SwiftUI/Enhancing-your-app-content-with-tab-navigation) — SwiftUI
-
-[`UITabBar`](https://developer.apple.com/documentation/UIKit/UITabBar) — UIKit
-
-[Elevating your iPad app with a tab bar and sidebar](https://developer.apple.com/documentation/UIKit/elevating-your-ipad-app-with-a-tab-bar-and-sidebar) — UIKit
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/1AAA030E-2ECA-47D8-AE09-6D7B72A840F6/10044_wide_250x141_1x.jpg) Get to know the new design system ](https://developer.apple.com/videos/play/wwdc2025/356)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/873F40BE-101A-4C0D-99F0-F5C7CE7B47A3/10046_wide_250x141_1x.jpg) Elevate the design of your iPad app ](https://developer.apple.com/videos/play/wwdc2025/208)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/tab-bars#Change-log)
-
-Date| Changes  
----|---  
-December 16, 2025| Updated guidance for Liquid Glass.  
-July 28, 2025| Added guidance for Liquid Glass.  
-September 9, 2024| Added art representing the tab bar in iPadOS 18.  
-August 6, 2024| Updated with guidance for the tab bar in iPadOS 18.  
-June 21, 2023| Updated to include guidance for visionOS.  
-  

package/templates/vault/hig-components-layout/references/tab-views.md

@@ -1,68 +0,0 @@
----
-title: "Tab views | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/tab-views
-
-# Tab views
-
-A tab view presents multiple mutually exclusive panes of content in the same area, which people can switch between using a tabbed control.
-
-![A stylized representation of a view with two labeled tabs, the first of which is selected. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/4b2dbd07b3c6fe1d349d6db6aad5890b/components-tab-view-intro%402x.png)
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/tab-views#Best-practices)
-
-**Use a tab view to present closely related areas of content.** The appearance of a tab view provides a strong visual indication of enclosure. People expect each tab to display content that is in some way similar or related to the content in the other tabs.
-
-**Make sure the controls within a pane affect content only in the same pane.** Panes are mutually exclusive, so ensure they’re fully self-contained.
-
-**Provide a label for each tab that describes the contents of its pane.** A good label helps people predict the contents of a pane before clicking or tapping its tab. In general, use nouns or short noun phrases for tab labels. A verb or short verb phrase may make sense in some contexts. Use title-style capitalization for tab labels.
-
-**Avoid using a pop-up button to switch between tabs.** A tabbed control is efficient because it requires a single click or tap to make a selection, whereas a pop-up button requires two. A tabbed control also presents all choices onscreen at the same time, whereas people must click a pop-up button to see its choices. Note that a pop-up button can be a reasonable alternative in cases where there are too many panes of content to reasonably display with tabs.
-
-**Avoid providing more than six tabs in a tab view.** Having more than six tabs can be overwhelming and create layout issues. If you need to present six or more tabs, consider another way to implement the interface. For example, you could instead present each tab as a view option in a pop-up button menu.
-
-For developer guidance, see [`NSTabView`](https://developer.apple.com/documentation/AppKit/NSTabView).
-
-## [Anatomy](https://developer.apple.com/design/human-interface-guidelines/tab-views#Anatomy)
-
-The tabbed control appears on the top edge of the content area. You can choose to hide the control, which is appropriate for an app that switches between panes programmatically.
-
-![An illustration of a window in which a three-tab tabbed control is centered on the top edge of the content view.](https://docs-assets.developer.apple.com/published/05bb7fbc6365c3bab10db218644756c3/tab-views-top%402x.png)
-
-When you hide the tabbed control, the content area can be borderless, bezeled, or bordered with a line. A borderless view can be solid or transparent.
-
-**In general, inset a tab view by leaving a margin of window-body area on all sides of a tab view.** This layout looks clean and leaves room for additional controls that aren’t directly related to the contents of the tab view. You can extend a tab view to meet the window edges, but this layout is unusual.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/tab-views#Platform-considerations)
-
- _Not supported in iOS, iPadOS, tvOS, or visionOS._
-
-### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/tab-views#iOS-iPadOS)
-
-For similar functionality, consider using a [segmented control](https://developer.apple.com/design/human-interface-guidelines/segmented-controls) instead.
-
-### [watchOS](https://developer.apple.com/design/human-interface-guidelines/tab-views#watchOS)
-
-watchOS displays tab views using [page controls](https://developer.apple.com/design/human-interface-guidelines/components/presentation/page-controls). For developer guidance, see [`TabView`](https://developer.apple.com/documentation/SwiftUI/TabView) and [`verticalPage`](https://developer.apple.com/documentation/SwiftUI/TabViewStyle/verticalPage).
-
-![An illustration showing the page control next to the Digital Crown on Apple Watch. The current dot is enlarged, indicating that people can scroll through the current content, as well as scroll between pages.](https://docs-assets.developer.apple.com/published/10938a94cb663210f148e0fbce431e70/tab-view-watch-vertical%402x.png)
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/tab-views#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/tab-views#Related)
-
-[Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars)
-
-[Segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/tab-views#Developer-documentation)
-
-[`TabView`](https://developer.apple.com/documentation/SwiftUI/TabView) — SwiftUI
-
-[`NSTabView`](https://developer.apple.com/documentation/AppKit/NSTabView) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/tab-views#Change-log)
-
-Date| Changes  
----|---  
-June 5, 2023| Added guidance for using tab views in watchOS.  
-  

package/templates/vault/hig-components-layout/references/windows.md

@@ -1,188 +0,0 @@
----
-title: "Windows | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/windows
-
-# Windows
-
-A window presents UI views and components in your app or game.
-
-![A stylized representation of a window with close, minimize, and full-screen buttons. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/3c5ea22db1d7d414c160c95ed7f62ec9/components-window-intro%402x.png)
-
-In iPadOS, macOS, and visionOS, windows help define the visual boundaries of app content and separate it from other areas of the system, and enable multitasking workflows both within and between apps. Windows include system-provided interface elements such as frames and window controls that let people open, close, resize, and relocate them.
-
-Conceptually, apps use two types of windows to display content:
-
-  * A _primary_ window presents the main navigation and content of an app, and actions associated with them.
-
-  * An _auxiliary_ window presents a specific task or area in an app. Dedicated to one experience, an auxiliary window doesn’t allow navigation to other app areas, and it typically includes a button people use to close it after completing the task.
-
-
-
-
-For guidance laying out content within a window on any platform, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout); for guidance laying out content in Apple Vision Pro space, see [Spatial layout](https://developer.apple.com/design/human-interface-guidelines/spatial-layout). For developer guidance, see [Windows](https://developer.apple.com/documentation/SwiftUI/Windows).
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/windows#Best-practices)
-
-**Make sure that your windows adapt fluidly to different sizes to support multitasking and multiwindow workflows.** For guidance, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout) and [Multitasking](https://developer.apple.com/design/human-interface-guidelines/multitasking).
-
-**Choose the right moment to open a new window.** Opening content in a separate window is great for helping people multitask or preserve context. For example, Mail opens a new window whenever someone selects the Compose action, so both the new message and the existing email are visible at the same time. However, opening new windows excessively creates clutter and can make navigating your app more confusing. Avoid opening new windows as default behavior unless it makes sense for your app.
-
-**Consider providing the option to view content in a new window.** While it’s best to avoid opening new windows as default behavior unless it benefits your user experience, it’s also great to give people the flexibility of viewing content in multiple ways. Consider letting people view content in a new window using a command in a [context menu](https://developer.apple.com/design/human-interface-guidelines/context-menus) or in the [File menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#File-menu). For developer guidance, see [`OpenWindowAction`](https://developer.apple.com/documentation/SwiftUI/OpenWindowAction).
-
-**Avoid creating custom window UI.** System-provided windows look and behave in a way that people understand and recognize. Avoid making custom window frames or controls, and don’t try to replicate the system-provided appearance. Doing so without perfectly matching the system’s look and behavior can make your app feel broken.
-
-**Use the term _window_ in user-facing content.** The system refers to app windows as _windows_ regardless of type. Using different terms — including _scene_ , which refers to window implementation — is likely to confuse people.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/windows#Platform-considerations)
-
- _Not supported in iOS, tvOS, or watchOS._
-
-### [iPadOS](https://developer.apple.com/design/human-interface-guidelines/windows#iPadOS)
-
-Windows present in one of two ways depending on a person’s choice in Multitasking & Gestures settings.
-
-  * **Full screen.** App windows fill the entire screen, and people switch between them — or between multiple windows of the same app — using the app switcher.
-
-  * **Windowed.** People can freely resize app windows. Multiple windows can be onscreen at once, and people can reposition them and bring them to the front. The system remembers window size and placement even when an app is closed.
-
-
-
-
-  * Full screen 
-  * Windowed 
-
-
-
-![A screenshot of the Notes app in full screen on iPad, with an open document titled Nature Walks. The app interface fills the entire screen, with no visible border to the window.](https://docs-assets.developer.apple.com/published/5daa697ab73d7e08de1e4fa78a56bfcb/windows-ipad-notes-fullscreen%402x.png)
-
-![A screenshot of the Notes app  in a window on iPad, with an open document titled Nature Walks. The document window occupies the center of the screen, with the Home Screen background filling the rest of the screen behind it, and the Dock at the bottom.](https://docs-assets.developer.apple.com/published/0d1eca9806c6d60816eb9b6f436c28d3/windows-ipad-notes-windowed%402x.png)
-
-**Make sure window controls don’t overlap toolbar items.** When windowed, app windows include window controls at the leading edge of the toolbar. If your app has toolbar buttons at the leading edge, they might be hidden by window controls when they appear. To prevent this, instead of placing buttons directly on the leading edge, move them inward when the window controls appear.
-
-**Consider letting people use a gesture to open content in a new window.** For example, people can use the pinch gesture to expand a Notes item into a new window. For developer guidance, see [`collectionView(_:sceneActivationConfigurationForItemAt:point:)`](https://developer.apple.com/documentation/UIKit/UICollectionViewDelegate/collectionView\(_:sceneActivationConfigurationForItemAt:point:\)) (to transition from a collection view item), or [`UIWindowScene.ActivationInteraction`](https://developer.apple.com/documentation/UIKit/UIWindowScene/ActivationInteraction) (to transition from an item in any other view).
-
-Tip
-
-If you only need to let people view one file, you can present it without creating your own window, but you must support multiple windows in your app. For developer guidance, see [`QLPreviewSceneActivationConfiguration`](https://developer.apple.com/documentation/QuickLook/QLPreviewSceneActivationConfiguration).
-
-### [macOS](https://developer.apple.com/design/human-interface-guidelines/windows#macOS)
-
-In macOS, people typically run several apps at the same time, often viewing windows from multiple apps on one desktop and switching frequently between different windows — moving, resizing, minimizing, and revealing the windows to suit their work style.
-
-To learn about setting up a window to display your game in macOS, see [Managing your game window for Metal in macOS](https://developer.apple.com/documentation/Metal/managing-your-game-window-for-metal-in-macos).
-
-#### [macOS window anatomy](https://developer.apple.com/design/human-interface-guidelines/windows#macOS-window-anatomy)
-
-A macOS window consists of a frame and a body area. People can move a window by dragging the frame and can often resize the window by dragging its edges.
-
-The _frame_ of a window appears above the body area and can include window controls and a [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars). In rare cases, a window can also display a bottom bar, which is a part of the frame that appears below body content.
-
-#### [macOS window states](https://developer.apple.com/design/human-interface-guidelines/windows#macOS-window-states)
-
-A macOS window can have one of three states:
-
-  * **Main.** The frontmost window that people view is an app’s main window. There can be only one main window per app.
-
-  * **Key.** Also called the _active window_ , the key window accepts people’s input. There can be only one key window onscreen at a time. Although the front app’s main window is usually the key window, another window — such as a panel floating above the main window — might be key instead. People typically click a window to make it key; when people click an app’s Dock icon to bring all of that app’s windows forward, only the most recently accessed window becomes key.
-
-  * **Inactive.** A window that’s not in the foreground is an inactive window.
-
-
-
-
-The system gives main, key, and inactive windows different appearances to help people visually identify them. For example, the key window uses color in the title bar options for closing, minimizing, and zooming; inactive windows and main windows that aren’t key use gray in these options. Also, inactive windows don’t use [vibrancy](https://developer.apple.com/design/human-interface-guidelines/materials) (an effect that can pull color into a window from the content underneath it), which makes them appear subdued and seem visually farther away than the main and key windows.
-
-![An illustration of a stack of three windows, as follows: An inactive window in the background, an app’s main window in the middle, and a key window appearing above the other two windows.](https://docs-assets.developer.apple.com/published/7ecd910726f347fb452d9ecd2b492d22/window-states%402x.png)
-
-Note
-
-Some windows — typically, panels like Colors or Fonts — become the key window only when people click the window’s title bar or a component that requires keyboard input, such as a text field.
-
-**Make sure custom windows use the system-defined appearances.** People rely on the visual differences between windows to help them identify the foreground window and know which window will accept their input. When you use system-provided components, a window’s background and button appearances update automatically when the window changes state; if you use custom implementations, you need to do this work yourself.
-
-**Avoid putting critical information or actions in a bottom bar, because people often relocate a window in a way that hides its bottom edge.** If you must include one, use it only to display a small amount of information directly related to a window’s contents or to a selected item within it. For example, Finder uses a bottom bar (called the status bar) to display the total number of items in a window, the number of selected items, and how much space is available on the disk. A bottom bar is small, so if you have more information to display, consider using an inspector, which typically presents information on the trailing side of a split view.
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS)
-
-visionOS defines two main window styles: default and volumetric. Both a default window (called a _window_) and a volumetric window (called a _volume_) can display 2D and 3D content, and people can view multiple windows and volumes at the same time in both the Shared Space and a Full Space.
-
-![An illustration representing a window in visionOS. The illustration consists of two parallel rounded rectangles, slightly separated and displayed on an angle, positioned above a window bar.](https://docs-assets.developer.apple.com/published/e8dc51484c2e5f3289a5f6a878f4c47d/visionos-window-style-2d-window%402x.png)A window
-
-![An illustration representing a volume in visionOS. The illustration consists of a translucent cube. The base of the cube is darker than the other sides. The front of the cube is positioned above a window bar.](https://docs-assets.developer.apple.com/published/92d953d099f72f9909c47bad408f4c9b/visionos-window-style-3d-volume%402x.png)A volume
-
-Note
-
-visionOS also defines the _plain_ window style, which is similar to the default style, except that the upright plane doesn’t use the glass background. For developer guidance, see [`PlainWindowStyle`](https://developer.apple.com/documentation/SwiftUI/PlainWindowStyle).
-
-The system defines the initial position of the first window or volume people open in your app or game. In both the Shared Space and a Full Space, people can move windows and volumes to new locations.
-
-#### [visionOS windows](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS-windows)
-
-The default window style consists of an upright plane that uses an unmodifiable background [material](https://developer.apple.com/design/human-interface-guidelines/materials) called _glass_ and includes a close button, window bar, and resize controls that let people close, move, and resize the window. A window can also include a Share button, [tab bar](https://developer.apple.com/design/human-interface-guidelines/tab-bars), [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars), and one or more [ornaments](https://developer.apple.com/design/human-interface-guidelines/ornaments). By default, visionOS uses dynamic [scale](https://developer.apple.com/design/human-interface-guidelines/spatial-layout#Scale) to help a window’s size appear to remain consistent regardless of its proximity to the viewer. For developer guidance, see [`DefaultWindowStyle`](https://developer.apple.com/documentation/SwiftUI/DefaultWindowStyle).
-
-![A screenshot of a window for an app named 'Hello World' in visionOS. The window includes text and buttons for entering different experiences.](https://docs-assets.developer.apple.com/published/95650cb19e1930e6b08ca5aa3b5b06a0/visionos-window-2d%402x.png)A window
-
-**Prefer using a window to present a familiar interface and to support familiar tasks.** Help people feel at home in your app by displaying an interface they’re already comfortable with, reserving more [immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences) for the meaningful content and activities you offer. If you want to showcase bounded 3D content like a game board, consider using a [volume](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS-volumes).
-
-**Retain the window’s glass background.** The default glass background helps your content feel like part of people’s surroundings while adapting dynamically to lighting and using specular reflections and shadows to communicate the window’s scale and position. Removing the glass material tends to cause UI elements and text to become less legible and to no longer appear related to each other; using an opaque background obscures people’s surroundings and can make a window feel constricting and heavy.
-
-**Choose an initial window size that minimizes empty areas within it.** By default, a window measures 1280x720 pt. When a window first opens, the system places it about two meters in front of the wearer, giving it an apparent width of about three meters. Too much empty space inside a window can make it look unnecessarily large while also obscuring other content in people’s space.
-
-**Aim for an initial shape that suits a window’s content.** For example, a default Keynote window is wide because slides are wide, whereas a default Safari window is tall because most webpages are much longer than they are wide. For games, a tower-building game is likely to open in a taller window than a driving game.
-
-**Choose a minimum and maximum size for each window to help keep your content looking great.** People appreciate being able to resize windows as they customize their space, but you need to make sure your layout adjusts well across all sizes. If you don’t set a minimum and maximum size for a window, people could make it so small that UI elements overlap or so large that your app or game becomes unusable. For developer guidance, see [Positioning and sizing windows](https://developer.apple.com/documentation/visionOS/positioning-and-sizing-windows).
-
-![A screenshot of a window for an app in visionOS. The window includes text that discusses objects in orbit, and it includes buttons for viewing a satellite, the moon, and a telescope. The satellite button is selected and a 3D satellite is displayed.](https://docs-assets.developer.apple.com/published/db1e41fe4000281898003f792ff037c8/visionos-window-2d-with-volume%402x.png)A window containing 3D content
-
-**Minimize the depth of 3D content you display in a window.** The system adds highlights and shadows to the views and controls within a window, giving them the appearance of [depth](https://developer.apple.com/design/human-interface-guidelines/spatial-layout#Depth) and helping them feel more substantial, especially when people view the window from an angle. Although you can display 3D content in a window, the system clips it if the content extends too far from the window’s surface. To display 3D content that has greater depth, use a volume.
-
-#### [visionOS volumes](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS-volumes)
-
-You can use a volume to display 2D or 3D content that people can view from any angle. A volume includes window-management controls just like a window, but unlike in a window, a volume’s close button and window bar shift position to face the viewer as they move around the volume. For developer guidance, see [`VolumetricWindowStyle`](https://developer.apple.com/documentation/SwiftUI/VolumetricWindowStyle).
-
-![A screenshot of a volume containing a 3D globe in visionOS, beside a window.](https://docs-assets.developer.apple.com/published/99098a290c36254e48329511216e1d5a/visionos-window-3d%402x.png)A volume
-
-**Prefer using a volume to display rich, 3D content.** In contrast, if you want to present a familiar, UI-centric interface, it generally works best to use a [window](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS-windows).
-
-**Place 2D content so it looks good from multiple angles.** Because a person’s perspective changes as they move around a volume, the location of 2D content within it might appear to change in ways that don’t make sense. To pin 2D content to specific areas of 3D content inside a volume, you can use an attachment.
-
-**In general, use dynamic scaling.** Dynamic scaling helps a volume’s content remain comfortably legible and easy to interact with, even when it’s far away from the viewer. On the other hand, if you want a volume’s content to represent a real-world object, like a product in a retail app, you can use fixed scaling (this is the default).
-
-**Take advantage of the default baseplate appearance to help people discern the edges of a volume.** In visionOS 2 and later, the system automatically makes a volume’s horizontal “floor,” or _baseplate_ , visible by displaying a gentle glow around its border when people look at it. If your content doesn’t fill the volume, the system-provided glow can help people become aware of the volume’s edges, which can be particularly useful in keeping the resize control easy to find. On the other hand, if your content is full bleed or fills the volume’s bounds — or if you display a custom baseplate appearance — you may not want the default glow.
-
-**Consider offering high-value content in an ornament.** In visionOS 2 and later, a volume can include an ornament in addition to a toolbar and tab bar. You can use an ornament to reduce clutter in a volume and elevate important views or controls. When you use an attachment anchor to specify the ornament’s location, such as `topBack` or `bottomFront`, the ornament remains in the same position, relative to the viewer’s perspective, as they move around the volume. Be sure to avoid placing an ornament on the same edge as a toolbar or tab bar, and prefer creating only one additional ornament to avoid overshadowing the important content in your volume. For developer guidance, see [`ornament(visibility:attachmentAnchor:contentAlignment:ornament:)`](https://developer.apple.com/documentation/SwiftUI/View/ornament\(visibility:attachmentAnchor:contentAlignment:ornament:\)).
-
-**Choose an alignment that supports the way people interact with your volume.** As people move a volume, the baseplate can remain parallel to the floor of a person’s surroundings, or it can tilt to match the angle at which a person is looking. In general, a volume that remains parallel to the floor works well for content that people don’t interact with much, whereas a volume that tilts to match where a person is looking can keep content comfortably usable, even when the viewer is reclining.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/windows#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/windows#Related)
-
-[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
-
-[Split views](https://developer.apple.com/design/human-interface-guidelines/split-views)
-
-[Multitasking](https://developer.apple.com/design/human-interface-guidelines/multitasking)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/windows#Developer-documentation)
-
-[Windows](https://developer.apple.com/documentation/SwiftUI/Windows) — SwiftUI
-
-[`WindowGroup`](https://developer.apple.com/documentation/SwiftUI/WindowGroup) — SwiftUI
-
-[`UIWindow`](https://developer.apple.com/documentation/UIKit/UIWindow) — UIKit
-
-[`NSWindow`](https://developer.apple.com/documentation/AppKit/NSWindow) — AppKit
-
-#### [Videos](https://developer.apple.com/design/human-interface-guidelines/windows#Videos)
-
-[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/873F40BE-101A-4C0D-99F0-F5C7CE7B47A3/10046_wide_250x141_1x.jpg) Elevate the design of your iPad app ](https://developer.apple.com/videos/play/wwdc2025/208)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/windows#Change-log)
-
-Date| Changes  
----|---  
-June 9, 2025| Added best practices, and updated with guidance for resizable windows in iPadOS.  
-June 10, 2024| Updated to include guidance for using volumes in visionOS 2 and added game-specific examples.  
-June 21, 2023| Updated to include guidance for visionOS.  
-