@ngxtm/devkit 3.14.0 → 3.16.0

package/skills/hig-components-menus/references/buttons.md

@@ -0,0 +1,261 @@
+---
+title: "Buttons | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/buttons
+
+# Buttons
+
+A button initiates an instantaneous action.
+
+![A stylized representation of two horizontally aligned 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/15781cd4e57f0e78b7a388a3fa009fa8/components-buttons-intro%402x.png)
+
+Versatile and highly customizable, buttons give people simple, familiar ways to do tasks in your app. In general, a button combines three attributes to clearly communicate its function:
+
+  * **Style.** A visual style based on size, color, and shape.
+
+  * **Content.** A symbol (or icon), text label, or both that a button displays to convey its purpose.
+
+  * **Role.** A system-defined role that identifies a button’s semantic meaning and can affect its appearance.
+
+
+
+
+There are also many button-like components that have distinct appearances and behaviors for specific use cases, like [toggles](https://developer.apple.com/design/human-interface-guidelines/toggles), [pop-up buttons](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons), and [segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/buttons#Best-practices)
+
+When buttons are instantly recognizable and easy to understand, an app tends to feel intuitive and well designed.
+
+**Make buttons easy for people to use.** It’s essential to include enough space around a button so that people can visually distinguish it from surrounding components and content. Giving a button enough space is also critical for helping people select or activate it, regardless of the method of input they use. As a general rule, a button needs a hit region of at least 44x44 pt — in visionOS, 60x60 pt — to ensure that people can select it easily, whether they use a fingertip, a pointer, their eyes, or a remote.
+
+**Always include a press state for a custom button.** Without a press state, a button can feel unresponsive, making people wonder if it’s accepting their input.
+
+## [Style](https://developer.apple.com/design/human-interface-guidelines/buttons#Style)
+
+System buttons offer a range of styles that support customization while providing built-in interaction states, accessibility support, and appearance adaptation. Different platforms define different styles that help you communicate hierarchies of actions in your app.
+
+**In general, use a button that has a prominent visual style for the most likely action in a view.** To draw people’s attention to a specific button, use a prominent button style so the system can apply an accent color to the button’s background. Buttons that use color tend to be the most visually distinctive, helping people quickly identify the actions they’re most likely to use. Keep the number of prominent buttons to one or two per view. Presenting too many prominent buttons increases cognitive load, requiring people to spend more time considering options before making a choice.
+
+**Use style — not size — to visually distinguish the preferred choice among multiple options.** When you use buttons of the same size to offer two or more options, you signal that the options form a coherent set of choices. By contrast, placing two buttons of different sizes near each other can make the interface look confusing and inconsistent. If you want to highlight the preferred or most likely option in a set, use a more prominent button style for that option and a less prominent style for the remaining ones.
+
+**Avoid applying a similar color to button labels and content layer backgrounds.** If your app already has bright, colorful content in the content layer, prefer using the default monochromatic appearance of button labels. For more guidance, see [Liquid Glass color](https://developer.apple.com/design/human-interface-guidelines/color#Liquid-Glass-color).
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/buttons#Content)
+
+**Ensure that each button clearly communicates its purpose.** Depending on the platform, a button can contain a symbol (or icon), a text label, or both to help people understand what it does.
+
+Note
+
+In macOS and visionOS, the system displays a tooltip after people hover over a button for a moment. A tooltip displays a brief phrase that explains what a button does; for guidance, see [Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help).
+
+**Try to associate familiar actions with familiar icons.** For example, people can predict that a button containing the `square.and.arrow.up` symbol will help them perform share-related activities. If it makes sense to use an icon in your button, consider using an existing or customized [symbol](https://developer.apple.com/design/human-interface-guidelines/sf-symbols). For a list of symbols that represent common actions, see [Standard icons](https://developer.apple.com/design/human-interface-guidelines/icons#Standard-icons).
+
+**Consider using text when a short label communicates more clearly than an icon.** To use text, write a few words that succinctly describe what the button does. Using [title-style capitalization](https://help.apple.com/applestyleguide/#/apsgb744e4a3?sub=apdca93e113f1d64), consider starting the label with a verb to help convey the button’s action — for example, a button that lets people add items to their shopping cart might use the label “Add to Cart.”
+
+## [Role](https://developer.apple.com/design/human-interface-guidelines/buttons#Role)
+
+A system button can have one of the following roles:
+
+  * **Normal.** No specific meaning.
+
+  * **Primary.** The button is the default button — the button people are most likely to choose.
+
+  * **Cancel.** The button cancels the current action.
+
+  * **Destructive.** The button performs an action that can result in data destruction.
+
+
+
+
+A button’s role can have additional effects on its appearance. For example, a primary button uses an app’s accent color, whereas a destructive button uses the system red color.
+
+![An example alert with three system buttons, labeled Primary, Destructive, and Cancel. The primary button uses a blue accent color, the destructive button uses text in the system red color, and the cancel button appears as a standard button.](https://docs-assets.developer.apple.com/published/ffa011d457181b94f56257d7d59f71aa/buttons-roles-alert%402x.png)
+
+**Assign the primary role to the button people are most likely to choose.** When a primary button responds to the Return key, it makes it easy for people to quickly confirm their choice. In addition, when the button is in a temporary view — like a [sheet](https://developer.apple.com/design/human-interface-guidelines/sheets), an editable view, or an [alert](https://developer.apple.com/design/human-interface-guidelines/alerts) — assigning it the primary role means that the view can automatically close when people press Return.
+
+**Don’t assign the primary role to a button that performs a destructive action, even if that action is the most likely choice.** Because of its visual prominence, people sometimes choose a primary button without reading it first. Help people avoid losing content by assigning the primary role to nondestructive buttons.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/buttons#Platform-considerations)
+
+ _No additional considerations for tvOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/buttons#iOS-iPadOS)
+
+**Configure a button to display an activity indicator when you need to provide feedback about an action that doesn’t instantly complete.** Displaying an activity indicator within a button can save space in your user interface while clearly communicating the reason for the delay. To help clarify what’s happening, you can also configure the button to display a different label alongside the activity indicator. For example, the label “Checkout” could change to “Checking out…” while the activity indicator is visible. When a delay occurs after people click or tap your configured button, the system displays the activity indicator next to the original or alternative label, hiding the button image, if there is one.
+
+![An illustration of a button labeled Checkout.](https://docs-assets.developer.apple.com/published/f7a2f53cdd4755b1121c34f1df0e94ae/button-activity-indicator-hidden%402x.png)
+
+![An illustration of a button labeled Checking out, with an activity indicator on the leading side of the label.](https://docs-assets.developer.apple.com/published/f2d6023f16eed80487f72b630903d220/button-activity-indicator-visible%402x.png)
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/buttons#macOS)
+
+Several specific button types are unique to macOS.
+
+#### [Push buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Push-buttons)
+
+The standard button type in macOS is known as a _push button_. You can configure a push button to display text, a symbol, an icon, or an image, or a combination of text and image content. Push buttons can act as the default button in a view and you can tint them.
+
+**Use a flexible-height push button only when you need to display tall or variable height content.** Flexible-height buttons support the same configurations as regular push buttons — and they use the same corner radius and content padding — so they look consistent with other buttons in your interface. If you need to present a button that contains two lines of text or a tall icon, use a flexible-height button; otherwise, use a standard push button. For developer guidance, see [`NSButton.BezelStyle.flexiblePush`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/flexiblePush).
+
+**Append a trailing ellipsis to the title when a push button opens another window, view, or app.** Throughout the system, an ellipsis in a control title signals that people can provide additional input. For example, the Edit buttons in the AutoFill pane of Safari Settings include ellipses because they open other views that let people modify autofill values.
+
+**Consider supporting spring loading.** On systems with a Magic Trackpad, _spring loading_ lets people activate a button by dragging selected items over it and force clicking — that is, pressing harder — without dropping the selected items. After force clicking, people can continue dragging the items, possibly to perform additional actions.
+
+#### [Square buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Square-buttons)
+
+A _square button_ (also known as a _gradient button_) initiates an action related to a view, like adding or removing rows in a table.
+
+Square buttons contain symbols or icons — not text — and you can configure them to behave like push buttons, toggles, or pop-up buttons. The buttons appear in close proximity to their associated view — usually within or beneath it — so people know which view the buttons affect.
+
+**Use square buttons in a view, not in the window frame.** Square buttons aren’t intended for use in toolbars or status bars. If you need a button in a [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars), use a toolbar item.
+
+**Prefer using a symbol in a square button.** [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) provides a wide range of symbols that automatically receive appropriate coloring in their default state and in response to user interaction.
+
+**Avoid using labels to introduce square buttons.** Because square buttons are closely connected with a specific view, their purpose is generally clear without the need for descriptive text.
+
+For developer guidance, see [`NSButton.BezelStyle.smallSquare`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/smallSquare).
+
+#### [Help buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Help-buttons)
+
+A _help button_ appears within a view and opens app-specific help documentation.
+
+Help buttons are circular, consistently sized buttons that contain a question mark. For guidance on creating help documentation, see [Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help).
+
+**Use the system-provided help button to display your help documentation.** People are familiar with the appearance of the standard help button and know that choosing it opens help content.
+
+**When possible, open the help topic that’s related to the current context.** For example, the help button in the Rules pane of Mail settings opens the Mail User Guide to a help topic that explains how to change these settings. If no specific help topic applies directly to the current context, open the top level of your app’s help documentation when people choose a help button.
+
+**Include no more than one help button per window.** Multiple help buttons in the same context make it hard for people to predict the result of clicking one.
+
+**Position help buttons where people expect to find them.** Use the following locations for guidance.
+
+View style| Help button location  
+---|---  
+Dialog with dismissal buttons (like OK and Cancel)| Lower corner, opposite to the dismissal buttons and vertically aligned with them  
+Dialog without dismissal buttons| Lower-left or lower-right corner  
+Settings window or pane| Lower-left or lower-right corner  
+  
+**Use a help button within a view, not in the window frame.** For example, avoid placing a help button in a toolbar or status bar.
+
+**Avoid displaying text that introduces a help button.** People know what a help button does, so they don’t need additional descriptive text.
+
+#### [Image buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Image-buttons)
+
+An _image button_ appears in a view and displays an image, symbol, or icon. You can configure an image button to behave like a push button, toggle, or pop-up button.
+
+**Use an image button in a view, not in the window frame.** For example, avoid placing an image button in a toolbar or status bar. If you need to use an image as a button in a toolbar, use a toolbar item. See [Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars).
+
+**Include about 10 pixels of padding between the edges of the image and the button edges.** An image button’s edges define its clickable area even when they aren’t visible. Including padding ensures that a click registers correctly even if it’s not precisely within the image. In general, avoid including a system-provided border in an image button; for developer guidance, see [`isBordered`](https://developer.apple.com/documentation/AppKit/NSButton/isBordered).
+
+**If you need to include a label, position it below the image button.** For related guidance, see [Labels](https://developer.apple.com/design/human-interface-guidelines/labels).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/buttons#visionOS)
+
+A visionOS button typically includes a visible background that can help people see it, and the button plays sound to provide feedback when people interact with it.
+
+Video with custom controls. 
+
+Content description: A recording showing the top portion of a window in visionOS. The window contains several buttons, including a 'More' button, which receives the hover effect. The button is selected and a menu containing additional options appears. 
+
+Play 
+
+There are three standard button shapes in visionOS. Typically, an icon-only button uses a [`circle`](https://developer.apple.com/documentation/SwiftUI/ButtonBorderShape/circle) shape, a text-only button uses a [`roundedRectangle`](https://developer.apple.com/documentation/SwiftUI/ButtonBorderShape/roundedRectangle) or [`capsule`](https://developer.apple.com/documentation/SwiftUI/ButtonBorderShape/capsule) shape, and a button that includes both an icon and text uses the capsule shape.
+
+visionOS buttons use different visual styles to communicate four different interaction states.
+
+![An image of a circular button that contains an icon of an outlined square with rounded corners. The button background is dark and the dashed outline is white.](https://docs-assets.developer.apple.com/published/aed0b1c313448f088dd1ee24663db11e/visionos-button-state-idle%402x.png)Idle
+
+![An image of a circular button that contains an icon of an outlined square with rounded corners. The button background is medium dark and the outline is white.](https://docs-assets.developer.apple.com/published/29d708fd7985184cbee9d90d7684da92/visionos-button-state-hover%402x.png)Hover
+
+![An image of a circular button that contains an icon of an outlined square with rounded corners. The button background is white and the outline is black.](https://docs-assets.developer.apple.com/published/0b94e710605235dfca19ef853499cf26/visionos-button-state-selected%402x.png)Selected
+
+![An image of a circular button that contains an icon of an outlined square with rounded corners. The button background is very dark and the outline is light.](https://docs-assets.developer.apple.com/published/737120252765e5427161af32bb17e7fb/visionos-button-state-unavailable%402x.png)Unavailable
+
+Note
+
+In visionOS, buttons don’t support custom hover effects.
+
+In addition to the four states shown above, a button can also reveal a tooltip when people look at it for a brief time. In general, buttons that contain text don’t need to display a tooltip because the button’s descriptive label communicates what it does.
+
+Video with custom controls. 
+
+Content description: An animation showing a tooltip appearing beneath a visionOS button. 
+
+Play 
+
+In visionOS, buttons can have the following sizes.
+
+Shape| Mini (28 pt)| Small (32 pt)| Regular (44 pt)| Large (52 pt)| Extra large (64 pt)  
+---|---|---|---|---|---  
+Circular| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)  
+Capsule (text only)| | ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)|   
+Capsule (text and icon)| | | ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)|   
+Rounded rectangle| | ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)| ![A checkmark denoting availability.](https://docs-assets.developer.apple.com/published/9c1e6292b0ff3ee8f9e10917ad97f3da/table-availability-checkmark%402x.png)|   
+  
+**Prefer buttons that have a discernible background shape and fill.** It tends to be easier for people to see a button when it’s enclosed in a shape that uses a contrasting background fill. The exception is a button in a toolbar, context menu, alert, or [ornament](https://developer.apple.com/design/human-interface-guidelines/ornaments) where the shape and material of the larger component make the button comfortably visible. The following guidelines can help you ensure that a button looks good in different contexts:
+
+  * When a button appears on top of a glass [window](https://developer.apple.com/design/human-interface-guidelines/windows#visionOS), use the [`thin`](https://developer.apple.com/documentation/SwiftUI/Material/thin) material as the button’s background.
+
+  * When a button appears floating in space, use the [glass material](https://developer.apple.com/design/human-interface-guidelines/materials#visionOS) for its background.
+
+
+
+
+**Avoid creating a custom button that uses a white background fill and black text or icons.** The system reserves this visual style to convey the toggled state.
+
+**In general, prefer circular or capsule-shape buttons.** People’s eyes tend to be drawn toward the corners in a shape, making it difficult to keep looking at the shape’s center. The more rounded a button’s shape, the easier it is for people to look steadily at it. When you need to display a button by itself, prefer a capsule-shape button.
+
+**Provide enough space around a button to make it easy for people to look at it.** Aim to place buttons so their centers are always at least 60 pts apart. If your buttons measure 60 pts or larger, add 4 pts of padding around them to keep the hover effect from overlapping. Also, it’s usually best to avoid displaying small or mini buttons in a vertical stack or horizontal row.
+
+**Choose the right shape if you need to display text-labeled buttons in a stack or row.** Specifically, prefer the rounded-rectangle shape in a vertical stack of buttons and prefer the capsule shape in a horizontal row of buttons.
+
+**Use standard controls to take advantage of the audible feedback sounds people already know.** Audible feedback is especially important in visionOS, because the system doesn’t play haptics.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/buttons#watchOS)
+
+watchOS displays all inline buttons using the [`capsule`](https://developer.apple.com/documentation/SwiftUI/ButtonBorderShape/capsule) button shape. When you place a button inline with content, it gains a material effect that contrasts with the background to ensure legibility.
+
+![An illustration that represents a screen on Apple Watch, which includes capsule-shaped Primary and Secondary buttons.](https://docs-assets.developer.apple.com/published/79565402ab107166de9aa0fe6eab4e6d/buttons-watch-full-width%402x.png)
+
+**Use a toolbar to place buttons in the corners.** The system automatically moves the time and title to accommodate toolbar buttons. The system also applies the [Liquid Glass](https://developer.apple.com/design/human-interface-guidelines/materials#Liquid-Glass) appearance to toolbar buttons, providing a clear visual distinction from the content beneath them.
+
+![An illustration showing toolbar buttons in the top leading and trailing corners, as well as three toolbar buttons across the bottom of the screen.](https://docs-assets.developer.apple.com/published/28835a2c6f34513eb0758beef1f6015d/buttons-watch-toolbar-corners%402x.png)
+
+**Prefer buttons that span the width of the screen for primary actions in your app.** Full-width buttons look better and are easier for people to tap. If two buttons must share the same horizontal space, use the same height for both, and use images or short text titles for each button’s content.
+
+**Use toolbar buttons to provide either navigation to related areas or contextual actions for the view’s content.** These buttons provide access to additional information or secondary actions for the view’s content.
+
+**Use the same height for vertical stacks of one- and two-line text buttons.** As much as possible, use identical button heights for visual consistency.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/buttons#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/buttons#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)
+
+[Toggles](https://developer.apple.com/design/human-interface-guidelines/toggles)
+
+[Segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls)
+
+[Location button](https://developer.apple.com/design/human-interface-guidelines/privacy#Location-button)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/buttons#Developer-documentation)
+
+[`Button`](https://developer.apple.com/documentation/SwiftUI/Button) — SwiftUI
+
+[`UIButton`](https://developer.apple.com/documentation/UIKit/UIButton) — UIKit
+
+[`NSButton`](https://developer.apple.com/documentation/AppKit/NSButton) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/buttons#Change-log)
+
+Date| Changes  
+---|---  
+December 16, 2025| Updated guidance for Liquid Glass.  
+June 9, 2025| Updated guidance for button styles and content.  
+February 2, 2024| Noted that visionOS buttons don’t support custom hover effects.  
+December 5, 2023| Clarified some terminology and guidance for buttons in visionOS.  
+June 21, 2023| Updated to include guidance for visionOS.  
+June 5, 2023| Updated guidance for using buttons in watchOS.  
+  

package/skills/hig-components-menus/references/context-menus.md

@@ -0,0 +1,105 @@
+---
+title: "Context menus | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/context-menus
+
+# Context menus
+
+A context menu provides access to functionality that’s directly related to an item, without cluttering the interface.
+
+![A stylized representation of a contextual menu beneath a clicking pointer. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/6145c402544704012a48978cf5ceb87a/components-context-menu-intro%402x.png)
+
+Although a context menu provides convenient access to frequently used items, it’s hidden by default, so people might not know it’s there. To reveal a context menu, people generally choose a view or select some content and then perform an action, using the input modes their current configuration supports. For example:
+
+  * The system-defined touch or pinch and hold gesture in visionOS, iOS, and iPadOS
+
+  * Pressing the Control key while clicking a pointing device in macOS and iPadOS
+
+  * Using a secondary click on a Magic Trackpad in macOS or iPadOS
+
+
+
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/context-menus#Best-practices)
+
+**Prioritize relevancy when choosing items to include in a context menu.** A context menu isn’t for providing advanced or rarely used items; instead, it helps people quickly access the commands they’re most likely to need in their current context. For example, the context menu for a Mail message in the Inbox includes commands for replying and moving the message, but not commands for editing message content, managing mailboxes, or filtering messages.
+
+**Aim for a small number of menu items.** A context menu that’s too long can be difficult to scan and scroll.
+
+**Support context menus consistently throughout your app.** If you provide context menus for items in some places but not in others, people won’t know where they can use the feature and may think there’s a problem.
+
+**Always make context menu items available in the main interface, too.** For example, in Mail in iOS and iPadOS, the context menu items that are available for a message in the Inbox are also available in the toolbar of the message view. In macOS, an app’s menu bar menus list all the app’s commands, including those in various context menus.
+
+**If you need to use submenus to manage a menu’s complexity, keep them to one level.** A submenu is a menu item that reveals a secondary menu of logically related commands. Although submenus can shorten a context menu and clarify its commands, more than one level of submenu complicates the experience and can be difficult for people to navigate. If you need to include a submenu, give it an intuitive title that helps people predict its contents without opening it. For guidance, see [Submenus](https://developer.apple.com/design/human-interface-guidelines/menus#Submenus).
+
+**Hide unavailable menu items, don’t dim them.** Unlike a regular menu, which helps people discover actions they can perform even when the action isn’t available, a context menu displays only the actions that are relevant to the currently selected view or content. In macOS, the exceptions are the Cut, Copy, and Paste menu items, which may appear unavailable if they don’t apply to the current context.
+
+**Aim to place the most frequently used menu items where people are likely to encounter them first.** When a context menu opens, people often read it starting from the part that’s closest to where their finger or pointer revealed it. Depending on the location of the selected content, a context menu might open above or below it, so you might also need to reverse the order of items to match the position of the menu.
+
+**Show keyboard shortcuts in your app’s main menus, not in context menus.** Context menus already provide a shortcut to task-specific commands, so it’s redundant to display keyboard shortcuts too.
+
+**Follow best practices for using separators.** As with other types of menus, you can use separators to group items in a context menu and help people scan the menu more quickly. In general, you don’t want more than about three groups in a context menu. For guidance, see [Menus](https://developer.apple.com/design/human-interface-guidelines/menus).
+
+**In iOS, iPadOS, and visionOS, warn people about context menu items that can destroy data.** If you need to include potentially destructive items in your context menu — such as Delete or Remove — list them at the end of the menu and identify them as destructive (for developer guidance, see [`destructive`](https://developer.apple.com/documentation/UIKit/UIMenuElement/Attributes/destructive)). The system can display a destructive menu item using a red text color.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/context-menus#Content)
+
+A context menu seldom displays a title. In contrast, each item in a context menu needs to display a short label that clearly describes what it does. For guidance, see [Menus > Labels](https://developer.apple.com/design/human-interface-guidelines/menus#Labels).
+
+**Include a title in a context menu only if doing so clarifies the menu’s effect.** For example, when people select multiple Mail messages and tap the Mark toolbar button in iOS and iPadOS, the resulting context menu displays a title that states the number of selected messages, reminding people that the command they choose affects all the messages they selected.
+
+**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). For additional guidance, see [Menus](https://developer.apple.com/design/human-interface-guidelines/menus).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/context-menus#Platform-considerations)
+
+ _No additional considerations for tvOS. Not supported in watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/context-menus#iOS-iPadOS)
+
+**Provide either a context menu or an edit menu for an item, but not both.** If you provide both features for the same item, it can be confusing to people — and difficult for the system to detect their intent. See [Edit menus](https://developer.apple.com/design/human-interface-guidelines/edit-menus).
+
+**In iPadOS, consider using a context menu to let people create a new object in your app.** iPadOS lets you reveal a context menu when people perform a long press on the touchscreen or use a secondary click with an attached trackpad or keyboard. For example, Files lets people create a new folder by revealing a context menu in an area between existing files and folders.
+
+In iOS and iPadOS, a context menu can display a preview of the current content near the list of commands. People can choose a command in the menu or — in some cases — they can tap the preview to open it or drag it to another area.
+
+**Prefer a graphical preview that clarifies the target of a context menu’s commands.** For example, when people reveal a context menu on a list item in Notes or Mail, the preview shows a condensed version of the actual content to help people confirm that they’re working with the item they intend.
+
+**Ensure that your preview looks good as it animates.** As people reveal a context menu on an onscreen object, the system animates the preview image as it emerges from the content, dimming the screen behind the preview and the menu. It’s important to adjust the preview’s clipping path to match the shape of the preview image so that its contours, such as the rounded corners, don’t appear to change during animation. For developer guidance, see [`UIContextMenuInteractionDelegate`](https://developer.apple.com/documentation/UIKit/UIContextMenuInteractionDelegate).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/context-menus#macOS)
+
+On a Mac, a context menu is sometimes called a _contextual_ menu.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/context-menus#visionOS)
+
+**Consider using a context menu instead of a panel or inspector window to present frequently used functionality.** Minimizing the number of separate views or windows your app opens can help people keep their space uncluttered.
+
+**In general, avoid letting a context menu’s height exceed the height of the window.** In visionOS, a window includes system-provided components above and below its top and bottom edges, such as window-management controls and the Share menu, so a context menu that’s too tall could obscure them. As you consider the number of items to include, be guided by the ways people are likely to use your app. For example, people who use an app to accomplish in-depth, specialist tasks often expect to spend time learning a large number of sophisticated commands and might appreciate contextual access to them. On the other hand, people who use an app to perform a few simple actions may appreciate short contextual menus that are quick to scan and use.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/context-menus#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/context-menus#Related)
+
+[Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
+
+[Edit menus](https://developer.apple.com/design/human-interface-guidelines/edit-menus)
+
+[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)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/context-menus#Developer-documentation)
+
+[`contextMenu(menuItems:)`](https://developer.apple.com/documentation/SwiftUI/View/contextMenu\(menuItems:\)) — SwiftUI
+
+[`UIContextMenuInteraction`](https://developer.apple.com/documentation/UIKit/UIContextMenuInteraction) — UIKit
+
+[`popUpContextMenu(_:with:for:)`](https://developer.apple.com/documentation/AppKit/NSMenu/popUpContextMenu\(_:with:for:\)) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/context-menus#Change-log)
+
+Date| Changes  
+---|---  
+December 5, 2023| Added guidance on hiding unavailable menu items.  
+June 21, 2023| Updated to include guidance for visionOS.  
+September 14, 2022| Refined guidance on including a submenu and added a guideline on using a context menu to support object creation in an iPadOS app.  
+  

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

@@ -0,0 +1,84 @@
+---
+title: "Disclosure controls | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/disclosure-controls
+
+# Disclosure controls
+
+Disclosure controls reveal and hide information and functionality related to specific controls or views.
+
+![A stylized representation of collapsed and expanded disclosure 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/d9f8c2e1696219ad884582186a447524/components-disclosure-control-intro%402x.png)
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Best-practices)
+
+**Use a disclosure control to hide details until they’re relevant.** Place controls that people are most likely to use at the top of the disclosure hierarchy so they’re always visible, with more advanced functionality hidden by default. This organization helps people quickly find the most essential information without overwhelming them with too many detailed options.
+
+## [Disclosure triangles](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Disclosure-triangles)
+
+A disclosure triangle shows and hides information and functionality associated with a view or a list of items. For example, Keynote uses a disclosure triangle to show advanced options when exporting a presentation, and the Finder uses disclosure triangles to progressively reveal hierarchy when navigating a folder structure in list view.
+
+  * Collapsed 
+  * Expanded 
+
+
+
+![An illustration of three folders in a Finder list view. The folders are collapsed, with disclosure triangles on their leading edges pointing inward to indicate that they can be expanded to reveal their contents.](https://docs-assets.developer.apple.com/published/f2f0f58d9777abfc3a92f782963fbba6/disclosure-triangle-before%402x.png)
+
+![An illustration of three folders in a Finder list view. The first and third folders are collapsed, with disclosure triangles on their leading edges pointing inward to indicate that they can be expanded to reveal their contents. The second folder is expanded, with its disclosure triangle pointing down, revealing three subfolders inside.](https://docs-assets.developer.apple.com/published/88c62732eba28e9f3233e0dedf6d0946/disclosure-triangle-after%402x.png)
+
+A disclosure triangle points inward from the leading edge when its content is hidden and down when its content is visible. Clicking or tapping the disclosure triangle switches between these two states, and the view expands or collapses accordingly to accommodate the content.
+
+**Provide a descriptive label when using a disclosure triangle.** Make sure your labels indicate what is disclosed or hidden, like “Advanced Options.”
+
+For developer guidance, see [`NSButton.BezelStyle.disclosure`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/disclosure).
+
+## [Disclosure buttons](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Disclosure-buttons)
+
+A disclosure button shows and hides functionality associated with a specific control. For example, the macOS Save sheet shows a disclosure button next to the Save As text field. When people click or tap this button, the Save dialog expands to give advanced navigation options for selecting an output location for their document.
+
+A disclosure button points down when its content is hidden and up when its content is visible. Clicking or tapping the disclosure button switches between these two states, and the view expands or collapses accordingly to accommodate the content.
+
+  * Collapsed 
+  * Expanded 
+
+
+
+![A screenshot of a collapsed save dialog in macOS. The dialog includes a closed disclosure button that expands the dialog to reveal additional options.](https://docs-assets.developer.apple.com/published/6d405bc1e4bd3743e610bf3dd4e17161/disclosure-button-before%402x.png)
+
+![A screenshot of an expanded save dialog in macOS. The dialog includes an open disclosure button that collapses the dialog to hide some options.](https://docs-assets.developer.apple.com/published/1d543abc1f07f34a01c63a3aac067ccd/disclosure-button-after%402x.png)
+
+**Place a disclosure button near the content that it shows and hides.** Establish a clear relationship between the control and the expanded choices that appear when a person clicks or taps a button.
+
+**Use no more than one disclosure button in a single view.** Multiple disclosure buttons add complexity and can be confusing.
+
+For developer guidance, see [`NSButton.BezelStyle.pushDisclosure`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/pushDisclosure).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Platform-considerations)
+
+ _No additional considerations for macOS. Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS, visionOS](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#iOS-iPadOS-visionOS)
+
+Disclosure controls are available in iOS, iPadOS, and visionOS with the SwiftUI [`DisclosureGroup`](https://developer.apple.com/documentation/SwiftUI/DisclosureGroup) view.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Related)
+
+[Outline views](https://developer.apple.com/design/human-interface-guidelines/outline-views)
+
+[Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables)
+
+[Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Developer-documentation)
+
+[`DisclosureGroup`](https://developer.apple.com/documentation/SwiftUI/DisclosureGroup) — SwiftUI
+
+[`NSButton.BezelStyle.disclosure`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/disclosure) — AppKit
+
+[`NSButton.BezelStyle.pushDisclosure`](https://developer.apple.com/documentation/AppKit/NSButton/BezelStyle-swift.enum/pushDisclosure) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/disclosure-controls#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/49/1636D358-5C36-4027-B204-81FFE4D05B7D/3455_wide_250x141_1x.jpg) Stacks, Grids, and Outlines in SwiftUI ](https://developer.apple.com/videos/play/wwdc2020/10031)
+

package/skills/hig-components-menus/references/dock-menus.md

@@ -0,0 +1,40 @@
+---
+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/skills/hig-components-menus/references/edit-menus.md

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