bps-kit 1.0.1 → 1.0.3

package/templates/vault/hig-components-menus/references/dock-menus.md

@@ -1,40 +0,0 @@
----
-title: "Dock menus | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/dock-menus
-
-# Dock menus
-
-On a Mac, people can secondary click an app’s or game’s icon in the Dock to reveal a Dock menu, which presents both system-provided and custom items.
-
-![A stylized representation of a menu extending from an icon in the Dock. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/b09af2b90f697b3e25f1985cce93f4ab/components-dock-menu-intro%402x.png)
-
-The system-provided Dock menu items can vary depending on whether the app is open. For example, the Dock menu for Safari includes menu items for actions like viewing a current window or creating a new window.
-
-Note
-
-Although iOS and iPadOS don’t support a Dock menu, people can reveal a similar menu of system-provided and custom items — called Home Screen quick actions — when they long press an app icon on the Home Screen or in the Dock. For guidance, see [Home Screen quick actions](https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions).
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/dock-menus#Best-practices)
-
-As with all menus, you need to label Dock menu items succinctly and organize them logically. For guidance, see [Menus](https://developer.apple.com/design/human-interface-guidelines/menus).
-
-**Make custom Dock menu items available in other places, too.** Not everyone uses a Dock menu, so it’s important to offer the same commands elsewhere, like in your menu bar menus or within your interface.
-
-**Prefer high-value custom items for your Dock menu.** For example, a Dock menu can list all currently or recently open windows, making it a convenient way to jump to the window people want. Also consider listing a few of the actions that are most likely to be useful when your app isn’t frontmost or when there are no open windows. For example, Mail includes items for getting new mail and composing a new message in addition to listing all open windows.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/dock-menus#Platform-considerations)
-
- _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/dock-menus#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/dock-menus#Related)
-
-[Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
-
-[Home Screen quick actions](https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/dock-menus#Developer-documentation)
-
-[`applicationDockMenu(_:)`](https://developer.apple.com/documentation/AppKit/NSApplicationDelegate/applicationDockMenu\(_:\)) — AppKit
-

package/templates/vault/hig-components-menus/references/edit-menus.md

@@ -1,88 +0,0 @@
----
-title: "Edit menus | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/edit-menus
-
-# Edit menus
-
-An edit menu lets people make changes to selected content in the current view, in addition to offering related commands like Copy, Select, Translate, and Look Up.
-
-![A stylized representation of an edit menu extending from selected text. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/2ee5b60d3d9877b65df7633d0321550a/components-edit-menu-intro%402x.png)
-
-In addition to text, an edit menu’s commands can apply to many types of selectable content, such as images, files, and objects like contact cards, charts, or map locations. In iOS, iPadOS, and visionOS, the system automatically detects the data type of a selected item, which can result in the addition of a related action to the edit menu. For example, selecting an address can add an item like _Get directions_ to the edit menu.
-
-Edit menus can look and behave slightly differently in different platforms.
-
-  * In iOS, the edit menu displays commands in a compact, horizontal list that appears when people touch and hold or double-tap to select content in a view. People can tap a chevron on the trailing edge to expand it into a [context menu](https://developer.apple.com/design/human-interface-guidelines/context-menus).
-
-  * In iPadOS, the edit menu looks different depending on how people reveal it. When people use touch interactions to reveal the menu, it uses the compact, horizontal appearance. In contrast, when people use a keyboard or pointing device to reveal it, the edit menu opens directly in a context menu.
-
-  * In macOS, people can access editing commands in a context menu they can reveal while in an editing task, as well as through the app’s [Edit menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Edit-menu) in the menu bar.
-
-  * In visionOS, people use the standard [pinch and hold](https://developer.apple.com/design/human-interface-guidelines/gestures#Standard-gestures) gesture to open the edit menu as a horizontal bar, or they can open it in a context menu.
-
-
-
-
-Editing content is rare in tvOS and watchOS experiences, so the system doesn’t provide an edit menu in these platforms.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Best-practices)
-
-**Prefer the system-provided edit menu.** People are familiar with the contents and behavior of the system-provided component, so creating a custom menu that presents the same commands is redundant and likely to be confusing. For a list of standard edit menu commands, see [`UIResponderStandardEditActions`](https://developer.apple.com/documentation/UIKit/UIResponderStandardEditActions).
-
-**Let people reveal an edit menu using the system-defined interactions they already know.** For example, people expect to touch and hold on a touchscreen, pinch and hold in visionOS, or use a secondary click with an attached trackpad or keyboard. Although the interactions to reveal an edit menu can differ based on platform, people don’t appreciate having to learn a custom interaction to perform a standard task.
-
-**Offer commands that are relevant in the current context, removing or dimming commands that don’t apply.** For example, if nothing is selected, avoid showing options that require a selection, such as Copy or Cut. Similarly, avoid showing a Paste option when there’s nothing to paste.
-
-**List custom commands near relevant system-provided ones.** For example, if you offer custom formatting commands, you can help maintain the ordering people expect by listing them after the system-provided commands in the format section. Avoid overwhelming people with too many custom commands.
-
-**When it makes sense, let people select and copy noneditable text.** People appreciate being able to paste static content — such as an image caption or social media status — into a message, note, or web search. In general, let people copy content text, but not control labels.
-
-**Support undo and redo when possible.** Like all menus, an edit menu doesn’t require confirmation before performing its actions, so people can easily use undo and redo to recover a previous state. For guidance, see [Undo and redo](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo).
-
-**In general, avoid implementing other controls that perform the same functions as edit menu items.** People typically expect to choose familiar edit commands in an edit menu, or use standard keyboard shortcuts. Offering redundant controls can crowd your interface, giving you less space for presenting actions that people might not already know about.
-
-**Differentiate different types of deletion commands when necessary.** For example, a Delete menu item behaves the same as pressing a Delete key, but a Cut menu item copies the selected content to the system pasteboard before deleting it.
-
-## [Content](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Content)
-
-**Create short labels for custom commands.** Use verbs or short verb phrases that succinctly describe the action your command performs. For guidance, see [Labels](https://developer.apple.com/design/human-interface-guidelines/labels).
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Platform-considerations)
-
- _No additional considerations for visionOS. Not supported in tvOS or watchOS._
-
-### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/edit-menus#iOS-iPadOS)
-
-**Ensure your edit menu works well in both styles.** The system displays the compact, horizontal style when people use Multi-Touch gestures to reveal the edit menu, and the vertical style when people use a keyboard or pointing device to reveal it. For guidance using the vertical menu layout, see [Menus > iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/menus#iOS-iPadOS).
-
-**Adjust an edit menu’s placement, if necessary.** Depending on available space, the default menu position is above or below the insertion point or selection. The system also displays a visual indicator that points to the targeted content. Although you can’t change the shape of the menu or its pointer, you can change the menu’s position. For example, you might need to move the menu to prevent it from covering important content or parts of your interface.
-
-### [macOS](https://developer.apple.com/design/human-interface-guidelines/edit-menus#macOS)
-
-To learn about the order of items in a macOS app’s Edit menu, see [Edit menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Edit-menu).
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Related)
-
-[Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
-
-[Context menus](https://developer.apple.com/design/human-interface-guidelines/context-menus)
-
-[The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar)
-
-[Undo and redo](https://developer.apple.com/design/human-interface-guidelines/undo-and-redo)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Developer-documentation)
-
-[`UIEditMenuInteraction`](https://developer.apple.com/documentation/UIKit/UIEditMenuInteraction) — UIKit
-
-[`NSMenu`](https://developer.apple.com/documentation/AppKit/NSMenu) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/edit-menus#Change-log)
-
-Date| Changes  
----|---  
-June 21, 2023| Updated to include guidance for visionOS.  
-September 14, 2022| Added guidance on supporting both edit-menu styles in iPadOS.  
-  

package/templates/vault/hig-components-menus/references/menus.md

@@ -1,171 +0,0 @@
----
-title: "Menus | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/menus
-
-# Menus
-
-A menu reveals its options when people interact with it, making it a space-efficient way to present commands in your app or game.
-
-![A stylized representation of a menu containing a selected item and displaying a submenu. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/a64b5649dc039710622ba211979e116b/components-menus-intro%402x.png)
-
-Menus are ubiquitous in apps and games, so most people already know how to use them. Whether you use system-provided components or custom ones, people expect menus to behave in familiar ways. For example, people understand that opening a menu reveals one or more _menu items_ , each of which represents a command, option, or state that affects the current selection or context. The guidance for labeling and organizing menu items applies to all types of menus in all experiences.
-
-Note
-
-Several system-provided components also include menus that support specific use cases. For example, a [pop-up button](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons) or [pull-down button](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons) can reveal a menu of options directly related to its action; a [context menu](https://developer.apple.com/design/human-interface-guidelines/context-menus) lets people access a small number of frequently used actions relevant to their current view or task; and in macOS and iPadOS, [menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar) menus contain all the commands people can perform in the app or game.
-
-## [Labels](https://developer.apple.com/design/human-interface-guidelines/menus#Labels)
-
-A menu item’s label describes what it does and may include a symbol if it helps to clarify meaning. In an app, a menu item can also display the associated keyboard command, if there is one; in a game, a menu item rarely displays a keyboard command because a game typically needs to handle input from a wider range of devices and may offer game-specific mappings for various keys.
-
-Note
-
-Depending on menu layout, an iOS, iPadOS, or visionOS app can display a few unlabeled menu items that use only symbols or icons to identify them. For guidance, see [visionOS](https://developer.apple.com/design/human-interface-guidelines/menus#visionOS) and [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/menus#iOS-iPadOS).
-
-**For each menu item, write a label that clearly and succinctly describes it.** In general, label a menu item that initiates an action using a verb or verb phrase that describes the action, such as View, Close, or Select. For guidance labeling menu items that show and hide something in the interface or show the currently selected state of something, see [Toggled items](https://developer.apple.com/design/human-interface-guidelines/menus#Toggled-items). As with all the copy you write, let your app’s or game’s communication style guide the tone of the menu-item labels you create.
-
-**To be consistent with platform experiences, use title-style capitalization.** Although a game might have a different writing style, generally prefer using title-style capitalization, which capitalizes every word except articles, coordinating conjunctions, and short prepositions, and capitalizes the last word in the label, regardless of the part of speech. For complete guidance on this style of capitalization in English, see [title-style capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64).
-
-**Remove articles like _a_ , _an_ , and _the_ from menu-item labels to save space.** In English, articles always lengthen labels, but rarely enhance understanding. For example, changing a menu-item label from View Settings to View the Settings doesn’t provide additional clarification.
-
-**Show people when a menu item is unavailable.** An unavailable menu item often appears dimmed and doesn’t respond to interactions. If all of a menu’s items are unavailable, the menu itself needs to remain available so people can open it and learn about the commands it contains.
-
-**Append an ellipsis to a menu item’s label when the action requires more information before it can complete.** The ellipsis character (…) signals that people need to input information or make additional choices, typically within another view.
-
-## [Icons](https://developer.apple.com/design/human-interface-guidelines/menus#Icons)
-
-**Represent menu item actions with familiar icons.** Icons help people recognize common actions throughout your app. Use the same icons as the system to represent actions such as Copy, Share, and Delete, wherever they appear. For a list of icons that represent common actions, see [Standard icons](https://developer.apple.com/design/human-interface-guidelines/icons#Standard-icons).
-
-**Don’t display an icon if you can’t find one that clearly represents the menu item.** Not all menu items need an icon. Be careful when adding icons for custom menu items to avoid confusion with other existing actions, and don’t add icons just for the sake of ornamentation.
-
-![An illustration of a menu containing the days of the week. Each menu item is represented by a different symbol with no relation to the corresponding day.](https://docs-assets.developer.apple.com/published/e612c40d780feb72382a1d387aa556f6/menus-days-of-the-week-incorrect-icons%402x.png)
-
-![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
-
-![An illustration of a menu containing the days of the week with no accompanying symbols.](https://docs-assets.developer.apple.com/published/72bddfbe313d096cac7f09d136d2a601/menus-days-of-the-week-correct-no-icons%402x.png)
-
-![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
-
-**Use a single icon to introduce a group of similar items.** Instead of adding individual icons for each action, or reusing the same icon for all of them, establish a common theme with the symbol for the first item and rely on the menu item text to keep the remaining items distinct.
-
-![An illustration of an Edit menu that includes several similar Copy actions, with each represented by a different symbol.](https://docs-assets.developer.apple.com/published/7deb98def27f19a33794b9ec6cee02b4/menus-copy-actions-different-icons-incorrect%402x.png)
-
-![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
-
-![An illustration of an Edit menu that includes several similar Copy actions, with each represented by the same Copy symbol.](https://docs-assets.developer.apple.com/published/60241bb399a7e5faa06e9e53de4d858b/menus-copy-actions-repeated-icons-incorrect%402x.png)
-
-![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
-
-![An illustration of an Edit menu that includes several similar Copy actions. The first is represented by the Copy symbol, and the others with no symbol.](https://docs-assets.developer.apple.com/published/ee3e63278a8b0b023e35e963077f2596/menus-copy-actions-single-icon-correct%402x.png)
-
-![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
-
-## [Organization](https://developer.apple.com/design/human-interface-guidelines/menus#Organization)
-
-Organizing menu items in ways that reflect how people use your app or game can make your experience feel straightforward and easy to use.
-
-**Prefer listing important or frequently used menu items first.** People tend to start scanning a menu from the top, so listing high-priority items first often means that people can find what they want without reading the entire menu.
-
-**Consider grouping logically related items.** For example, grouping editing commands like Copy, Cut, and Paste or camera commands like Look Up, Look Down, and Look Left can help people remember where to find them. To help people visually distinguish such groups, use a separator. Depending on the platform and type of menu, a _separator_ appears between groups of items as a horizontal line or a short gap in the menu’s background appearance.
-
-**Prefer keeping all logically related commands in the same group, even if the commands don’t all have the same importance.** For example, people generally use Paste and Match Style much less often than they use Paste, but they expect to find both commands in the same group that contains more frequently used editing commands like Copy and Cut.
-
-**Be mindful of menu length.** People need more time and attention to read a long menu, which means they may miss the command they want. If a menu is too long, consider dividing it into separate menus. Alternatively, you might be able to use a submenu to shorten the list, such as listing difficulty levels in a submenu of a New Game menu item. The exception is when a menu contains user-defined or dynamically generated content, like the History and Bookmarks menus in Safari. People expect such a menu to accommodate all the items they add to it, so a long menu is fine, and scrolling is acceptable.
-
-## [Submenus](https://developer.apple.com/design/human-interface-guidelines/menus#Submenus)
-
-Sometimes, a menu item can reveal a set of closely related items in a subordinate list called a _submenu_. A menu item indicates the presence of a submenu by displaying a symbol — like a chevron — after its label. Submenus are functionally identical to menus, aside from their hierarchical positioning.
-
-**Use submenus sparingly.** Each submenu adds complexity to the interface and hides the items it contains. You might consider creating a submenu when a term appears in more than two menu items in the same group. For example, instead of offering separate menu items for Sort by Date, Sort by Score, and Sort by Time, a game could present a menu item that uses a submenu to list the sorting options Date, Score, and Time. It generally works well to use the repeated term — in this case, _Sort by_ — in the menu item’s label to help people predict the contents of the submenu.
-
-**Limit the depth and length of submenus.** It can be difficult for people to reveal multiple levels of hierarchical submenus, so it’s generally best to restrict them to a single level. Also, if a submenu contains more than about five items, consider creating a new menu.
-
-**Make sure a submenu remains available even when its nested menu items are unavailable.** A submenu item — like all menu items — needs to let people open it and learn about the commands it contains.
-
-**Prefer using a submenu to indenting menu items.** Using indentation is inconsistent with the system and doesn’t clearly express the relationships between the menu items.
-
-## [Toggled items](https://developer.apple.com/design/human-interface-guidelines/menus#Toggled-items)
-
-Menu items often represent attributes or objects that people can turn on or off. If you want to avoid listing a separate menu item for each state, it can be efficient to create a single, toggled menu item that communicates the current state and lets people change it.
-
-**Consider using a changeable label that describes an item’s current state.** For example, instead of listing two menu items like Show Map and Hide Map, you could include one menu item whose label changes from Show Map to Hide Map, depending on whether the map is visible.
-
-**Include a verb if a changeable label isn’t clear enough.** For example, people might not know whether the changeable labels HDR On and HDR Off describe actions or states. If you needed to clarify that these items represent actions, you could add verbs to the labels, like Turn HDR On and Turn HDR Off.
-
-**If necessary, display both menu items instead of one toggled item.** Sometimes, it helps people to view both actions or states at the same time. For example, a game could list both Take Account Online and Take Account Offline items, so when someone’s account is online, only the Take Account Offline menu item appears available.
-
-**Consider using a checkmark to show that an attribute is currently in effect.** It’s easy for people to scan for checkmarks in a list of attributes to find the ones that are selected. For example, in the standard Format > Font menu, checkmarks can make it easy for people notice the styles that apply to selected text.
-
-**Consider offering a menu item that makes it easy to remove multiple toggled attributes.** For example, if you let people apply several styles to selected text, it can work well to provide a menu item — such as Plain — that removes all applied formatting attributes at one time.
-
-## [In-game menus](https://developer.apple.com/design/human-interface-guidelines/menus#In-game-menus)
-
-In-game menus give players ways to control gameplay as well as determine [settings](https://developer.apple.com/design/human-interface-guidelines/settings) for the game as a whole.
-
-**Let players navigate in-game menus using the platform’s default interaction method.** People expect to use the same interactions to navigate your menus as they use for navigating other menus on the device. For example, players expect to navigate your game menus using touch in iOS and iPadOS, and direct and indirect gestures in visionOS.
-
-**Make sure your menus remain easy to open and read on all platforms you support.** Each platform defines specific sizes that work best for fonts and interaction targets. Sometimes, scaling your game content to display on a different screen — especially a mobile device screen — can make in-game menus too small for people to read or interact with. If this happens, modify the size of the tap targets and consider alternative ways to communicate the menu’s content. For guidance, see [Typography](https://developer.apple.com/design/human-interface-guidelines/typography) and [Touch controls](https://developer.apple.com/design/human-interface-guidelines/game-controls#Touch-controls).
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/menus#Platform-considerations)
-
- _No additional considerations for macOS, tvOS, or watchOS._
-
-### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/menus#iOS-iPadOS)
-
-In iOS and iPadOS, a menu can display items in one of the following three layouts.
-
-![A diagram showing small, medium, and large menu layouts, each containing the same set of menu items.](https://docs-assets.developer.apple.com/published/d04cabb2d7b38602590cd6d59d79a0a0/small-medium-large-menu-layouts%402x.png)
-
-  * **Small.** A row of four items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon, but no label.
-
-  * **Medium.** A row of three items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon above a short label.
-
-  * **Large (the default).** The menu displays all items in a list.
-
-
-
-
-For developer guidance, see [`preferredElementSize`](https://developer.apple.com/documentation/UIKit/UIMenu/preferredElementSize).
-
-**Choose a small or medium menu layout when it can help streamline people’s choices.** Consider using the medium layout if your app has three important actions that people often want to perform. For example, Notes uses the medium layout to give people a quick way to perform the Scan, Lock, and Pin actions. Use the small layout only for closely related actions that typically appear as a group, such as Bold, Italic, Underline, and Strikethrough. For each action, use a recognizable symbol that helps people identify the action without a label.
-
-### [visionOS](https://developer.apple.com/design/human-interface-guidelines/menus#visionOS)
-
-In visionOS, a menu can display items using the small or large layout styles that iOS and iPadOS define (for guidance, see [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/menus#iOS-iPadOS)). You can present a menu in your app or game from 3D content using a SwiftUI view. To ensure that your menu is always visible to people, even when other content occludes it, you can apply a [breakthrough effect](https://developer.apple.com/documentation/swiftui/view/presentationbreakthrougheffect\(_:\)). As in macOS, an open menu in a visionOS window can appear outside of the window’s boundaries.
-
-**Prefer displaying a menu near the content it controls.** Because people need to look at a menu item before tapping it, they might miss the item’s effect if the content it controls is too far away.
-
-![A partial screenshot showing an app window in visionOS. The window contains several buttons, including a 'More' button, which is selected. A menu containing a list of actions is displayed beneath the button.](https://docs-assets.developer.apple.com/published/b424693063f332d9edd65d555fec417e/visionos-notes-menu-popover-style%402x.png)
-
-**Prefer the subtle breakthrough effect in most cases.** This effect blends the presentation with its surrounding content, to maintain legibility and usability while preserving the depth and context of the scene. When you select [`automatic`](https://developer.apple.com/documentation/SwiftUI/BreakthroughEffect/automatic) for the breakthrough effect of a menu that overlaps with 3D content, the system applies [`subtle`](https://developer.apple.com/documentation/SwiftUI/BreakthroughEffect/subtle) by default. You can use [`prominent`](https://developer.apple.com/documentation/SwiftUI/BreakthroughEffect/prominent) if it’s important to display a menu prominently over the entire scene in your app or game, but this can disrupt the experience for people and potentially cause discomfort. Alternatively, you can use [`none`](https://developer.apple.com/documentation/SwiftUI/BreakthroughEffect/none) to fully occlude your menu behind other 3D content — for example, in a puzzle game that requires people to navigate around barriers — but this may make it difficult for people to see and access the menu.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/menus#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/menus#Related)
-
-[Pop-up buttons](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons)
-
-[Pull-down buttons](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons)
-
-[Context menus](https://developer.apple.com/design/human-interface-guidelines/context-menus)
-
-[The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/menus#Developer-documentation)
-
-[`Menu`](https://developer.apple.com/documentation/SwiftUI/Menu) — SwiftUI
-
-[Menus and shortcuts](https://developer.apple.com/documentation/UIKit/menus-and-shortcuts) — UIKit
-
-[Menus](https://developer.apple.com/documentation/AppKit/menus) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/menus#Change-log)
-
-Date| Changes  
----|---  
-December 16, 2025| Added guidance for presenting menus with breakthrough effects in visionOS.  
-July 28, 2025| Added guidance for representing menu items with icons.  
-June 10, 2024| Added guidance for in-game menus and included game-specific examples.  
-June 21, 2023| Updated to include guidance for visionOS.  
-September 14, 2022| Added guidelines for using the small, medium, and large menu layouts in iPadOS.  
-  

package/templates/vault/hig-components-menus/references/pop-up-buttons.md

@@ -1,70 +0,0 @@
----
-title: "Pop-up buttons | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons
-
-# Pop-up buttons
-
-A pop-up button displays a menu of mutually exclusive options.
-
-![A stylized representation of a pop-up button displaying a set of options. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/334ac7588fce25fa319c3ef611eca905/components-pop-up-button-intro%402x.png)
-
-After people choose an item from a pop-up button’s menu, the menu closes, and the button can update its content to indicate the current selection.
-
-![A screenshot of Calendar on iPhone, with a new calendar event open for editing. The editing screen contains controls for setting the details of the event, including its start and end dates, travel time, repeat interval, calendar, invitees, alert options, and attachments.](https://docs-assets.developer.apple.com/published/519951a89c3c840e87eca8c5760f4d90/pop-up-button-closed%402x.png)
-
-![A screenshot of Calendar on iPhone, with a new calendar event open for editing. A pop-up button menu emerges from the Repeat button, with options for choosing a repeat interval from a list of preset options, or creating a custom one.](https://docs-assets.developer.apple.com/published/61386d60280871ab2649bc5b2020aab5/pop-up-button-open%402x.png)
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Best-practices)
-
-**Use a pop-up button to present a flat list of mutually exclusive options or states.** A pop-up button helps people make a choice that affects their content or the surrounding view. Use a [pull-down button](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons) instead if you need to:
-
-  * Offer a list of actions
-
-  * Let people select multiple items
-
-  * Include a submenu
-
-
-
-
-**Provide a useful default selection.** A pop-up button can update its content to identify the current selection, but if people haven’t made a selection yet, it shows the default item you specify. When possible, make the default selection an item that most people are likely to want.
-
-**Give people a way to predict a pop-up button’s options without opening it.** For example, you can use an introductory label or a button label that describes the button’s effect, giving context to the options.
-
-**Consider using a pop-up button when space is limited and you don’t need to display all options all the time.** Pop-up buttons are a space-efficient way to present a wide array of choices.
-
-**If necessary, include a Custom option in a pop-up button’s menu to provide additional items that are useful in some situations.** Offering a Custom option can help you avoid cluttering the interface with items or controls that people need only occasionally. You can also display explanatory text below the list to help people understand how the options work.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Platform-considerations)
-
- _No additional considerations for iOS, macOS, or visionOS. Not supported in tvOS or watchOS._
-
-### [iPadOS](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#iPadOS)
-
-**Within a popover or modal view, consider using a pop-up button instead of a disclosure indicator to present multiple options for a list item.** For example, people can quickly choose an option from the pop-up button’s menu without navigating to a detail view. Consider using a pop-up button in this scenario when you have a fairly small, well-defined set of options that work well in a menu.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Related)
-
-[Pull-down buttons](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons)
-
-[Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)
-
-[Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Developer-documentation)
-
-[`MenuPickerStyle`](https://developer.apple.com/documentation/SwiftUI/MenuPickerStyle) — SwiftUI
-
-[`changesSelectionAsPrimaryAction`](https://developer.apple.com/documentation/UIKit/UIButton/changesSelectionAsPrimaryAction) — UIKit
-
-[`NSPopUpButton`](https://developer.apple.com/documentation/AppKit/NSPopUpButton) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons#Change-log)
-
-Date| Changes  
----|---  
-October 24, 2023| Added artwork.  
-September 14, 2022| Added a guideline on using a pop-up button in a popover or modal view in iPadOS.  
-  

package/templates/vault/hig-components-menus/references/pull-down-buttons.md

@@ -1,77 +0,0 @@
----
-title: "Pull-down buttons | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons
-
-# Pull-down buttons
-
-A pull-down button displays a menu of items or actions that directly relate to the button’s purpose.
-
-![A stylized representation of a pull-down menu displaying a set of items. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/dbe57c62e67b173fe5203469df675796/components-pull-down-button-intro%402x.png)
-
-After people choose an item in a pull-down button’s menu, the menu closes, and the app performs the chosen action.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Best-practices)
-
-**Use a pull-down button to present commands or items that are directly related to the button’s action.** The menu lets you help people clarify the button’s target or customize its behavior without requiring additional buttons in your interface. For example:
-
-  * An Add button could present a menu that lets people specify the item they want to add.
-
-  * A Sort button could use a menu to let people select an attribute on which to sort.
-
-  * A Back button could let people choose a specific location to revisit instead of opening the previous one.
-
-
-
-
-If you need to provide a list of mutually exclusive choices that aren’t commands, use a [pop-up button](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons) instead.
-
-**Avoid putting all of a view’s actions in one pull-down button.** A view’s primary actions need to be easily discoverable, so you don’t want to hide them in a pull-down button that people have to open before they can do anything.
-
-**Balance menu length with ease of use.** Because people have to interact with a pull-down button before they can view its menu, listing a minimum of three items can help the interaction feel worthwhile. If you need to list only one or two items, consider using alternative components to present them, such as buttons to perform actions and toggles or switches to present selections. In contrast, listing too many items in a pull-down button’s menu can slow people down because it takes longer to find a specific item.
-
-**Display a succinct menu title only if it adds meaning.** In general, a pull-down button’s content — combined with descriptive menu items — provides all the context people need, making a menu title unnecessary.
-
-**Let people know when a pull-down button’s menu item is destructive, and ask them to confirm their intent.** Menus use red text to highlight actions that you identify as potentially destructive. When people choose a destructive action, the system displays an [action sheet](https://developer.apple.com/design/human-interface-guidelines/action-sheets) (iOS) or [popover](https://developer.apple.com/design/human-interface-guidelines/popovers) (iPadOS) in which they can confirm their choice or cancel the action. Because an action sheet appears in a different location from the menu and requires deliberate dismissal, it can help people avoid losing data by mistake.
-
-**Include an interface icon with a menu item when it provides value.** If you need to clarify an item’s meaning, you can display an [icon](https://developer.apple.com/design/human-interface-guidelines/icons) or image after its label. Using [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) for this purpose can help you provide a familiar experience while ensuring that the symbol remains aligned with the text at every scale.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Platform-considerations)
-
- _No additional considerations for macOS or visionOS. Not supported in tvOS or watchOS._
-
-### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#iOS-iPadOS)
-
-Note
-
-You can also let people reveal a pull-down menu by performing a specific gesture on a button. For example, in iOS 14 and later, Safari responds to a touch and hold gesture on the Tabs button by displaying a menu of tab-related actions, like New Tab and Close All Tabs.
-
-**Consider using a More pull-down button to present items that don’t need prominent positions in the main interface.** A More button can help you offer a range of items where space is constrained, but it can also hinder discoverability. Although people generally understand that a More button offers additional functionality related to the current context, the ellipsis icon doesn’t necessarily help them predict its contents. To design an effective More button, weigh the convenience of its size against its impact on discoverability to find a balance that works in your app.
-
-![A screenshot of the Notes app on iPhone, open to a Notes document titled Nature Walks. The top toolbar includes a More button on the trailing edge.](https://docs-assets.developer.apple.com/published/5cdc980290422f59da0f79ab5f5efd13/menu-secondary-actions-collapsed%402x.png)
-
-![A screenshot of the Notes app on iPhone, open to a Notes document titled Nature Walks. The More button in the top toolbar is expanded, revealing the More menu with additional funtionality.](https://docs-assets.developer.apple.com/published/0d263e9b8df2b3f1e989a6383ebfaf5d/menu-secondary-actions-expanded%402x.png)
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Related)
-
-[Pop-up buttons](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons)
-
-[Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)
-
-[Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
-
-#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Developer-documentation)
-
-[`MenuPickerStyle`](https://developer.apple.com/documentation/SwiftUI/MenuPickerStyle) — SwiftUI
-
-[`showsMenuAsPrimaryAction`](https://developer.apple.com/documentation/UIKit/UIControl/showsMenuAsPrimaryAction) — UIKit
-
-[`pullsDown`](https://developer.apple.com/documentation/AppKit/NSPopUpButton/pullsDown) — AppKit
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons#Change-log)
-
-Date| Changes  
----|---  
-September 14, 2022| Refined guidance on designing a useful menu length.  
-