bps-kit 1.0.1 → 1.0.3

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

@@ -1,77 +0,0 @@
----
-name: hig-components-menus
-description: Apple HIG guidance for menu and button components including menus, context menus, dock menus, edit menus, the menu bar, toolbars, action buttons, pop-up buttons, pull-down buttons, disclosure...
-risk: unknown
-source: community
-date_added: '2026-02-27'
----
-
-# Apple HIG: Menus and Buttons
-
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
-
-## Key Principles
-
-1. **Menus should be contextual and predictable.** Standard items in standard locations. Follow platform conventions for ordering and grouping.
-
-2. **Use standard button styles.** System-defined styles communicate affordance and maintain visual consistency. Prefer them over custom designs.
-
-3. **Toolbars for frequent actions.** Most commonly used commands in the toolbar. Rarely used actions belong in menus.
-
-4. **Menu bar is the primary command interface on macOS.** Every command reachable from the menu bar. Toolbars and context menus supplement, not replace.
-
-5. **Context menus for secondary actions.** Right-click or long-press, relevant to the item under the pointer. Never put a command only in a context menu.
-
-6. **Pop-up buttons for mutually exclusive choices.** Select exactly one option from a set.
-
-7. **Pull-down buttons for action lists.** No current selection; they offer a set of commands.
-
-8. **Action buttons consolidate related actions** behind a single icon in toolbars or title bars.
-
-9. **Disclosure controls for progressive disclosure.** Show or hide additional content.
-
-10. **Dock menus: short and focused** on the most useful actions when the app is running.
-
-## Reference Index
-
-| Reference | Topic | Key content |
-|---|---|---|
-| [menus.md](references/menus.md) | General menu design | Item ordering, grouping, shortcuts |
-| [context-menus.md](references/context-menus.md) | Context menus | Right-click, long press, secondary actions |
-| [dock-menus.md](references/dock-menus.md) | Dock menus | macOS app-level actions, running state |
-| [edit-menus.md](references/edit-menus.md) | Edit menus | Undo, copy, paste, standard items |
-| [the-menu-bar.md](references/the-menu-bar.md) | Menu bar | macOS primary command interface, structure |
-| [toolbars.md](references/toolbars.md) | Toolbars | Frequent actions, customization, placement |
-| [buttons.md](references/buttons.md) | Buttons | System styles, sizing, affordance |
-| [action-button.md](references/action-button.md) | Action button | Grouped secondary actions, toolbar use |
-| [pop-up-buttons.md](references/pop-up-buttons.md) | Pop-up buttons | Mutually exclusive choice selection |
-| [pull-down-buttons.md](references/pull-down-buttons.md) | Pull-down buttons | Action lists, no current selection |
-| [disclosure-controls.md](references/disclosure-controls.md) | Disclosure controls | Progressive disclosure, show/hide |
-
-## Output Format
-
-1. **Component recommendation** -- which menu or button type and why.
-2. **Visual hierarchy** -- placement, sizing, grouping within the interface.
-3. **Platform-specific behavior** across iOS, iPadOS, macOS, visionOS.
-4. **Keyboard shortcuts** (macOS) -- standard and custom shortcuts for menu items and toolbar actions.
-
-## Questions to Ask
-
-1. Which platforms?
-2. Primary or secondary action?
-3. How many actions need to be available?
-4. macOS menu bar app?
-
-## Related Skills
-
-- **hig-components-search** -- Search fields, page controls alongside toolbars and menus
-- **hig-components-controls** -- Toggles, pickers, segmented controls complementing buttons
-- **hig-components-dialogs** -- Alerts, sheets, popovers triggered by menu items or buttons
-- **hig-inputs** -- Keyboard shortcuts and pointer interactions with menus and toolbars
-
----
-
-*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.

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

@@ -1,61 +0,0 @@
----
-title: "Action button | Apple Developer Documentation"
-source: https://developer.apple.com/design/human-interface-guidelines/action-button
-
-# Action button
-
-The Action button gives people quick access to their favorite features on supported iPhone and Apple Watch models.
-
-![A sketch of an arrow pointing toward the Action button on Apple Watch, suggesting initiating an action. The image is overlaid with rectangular and circular grid lines and is tinted purple to subtly reflect the purple in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/e9f0fbe50cec4b4b3ac0ef5daa14e321/inputs-action-button-intro%402x.png)
-
-On a supported device, people can use the Action button to run [App Shortcuts](https://developer.apple.com/design/human-interface-guidelines/app-shortcuts) or access system-provided functionality, like turning the flashlight on or off. On Apple Watch Ultra, the Action button supports activity-related actions, including workouts and dives.
-
-A person chooses a function for the Action button when they set up their device; later, they can adjust this choice in Settings. When someone associates an App Shortcut with the Action button, pressing the button runs the App Shortcut similarly to using their voice with Siri or tapping it in Spotlight.
-
-When designing your app or game, think of the Action button as another way for someone to quickly access a function that they use on a regular basis.
-
-## [Best practices](https://developer.apple.com/design/human-interface-guidelines/action-button#Best-practices)
-
-**Support the Action button with a set of your app’s essential functions.** For example, if your cooking app includes an egg timer, a “Start Egg Timer” action might be one that people want to initiate when they press the Action button. You don’t need to offer an App Shortcut that opens your app, because the system provides this function already. Your app icon, widgets, and Apple Watch complications give people other quick ways to open your app. For additional guidance, see [App Shortcuts](https://developer.apple.com/design/human-interface-guidelines/app-shortcuts).
-
-**For each action you support, write a short label that succinctly describes it.** People see your labels when they visit Settings to configure the Action button’s behavior. Create labels that use [title-style capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64), begin with a verb, use present tense, and exclude articles and prepositions. Keep labels as short as possible, with a maximum of three words. For example, use “Start Race” instead of “Started Race” or “Start the Race.”
-
-**Prefer letting the system show people how to use the Action button with your app.** When you support the Action button, the system automatically helps people configure it to initiate one of your app’s functions. Avoid creating content that repeats the guidance offered in Settings for the Action button, or other usage tips the system provides.
-
-## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/action-button#Platform-considerations)
-
- _Not supported in iPadOS, macOS, tvOS, or visionOS._
-
-### [iOS](https://developer.apple.com/design/human-interface-guidelines/action-button#iOS)
-
-**Let people use your actions without leaving their current context.** When possible, make use of lightweight multitasking capabilities like [Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities) and custom snippets to provide functionality without opening your app. For example, the “Set Timer” action doesn’t launch the Clock app; it prompts people to set a duration for the timer, and then launches a Live Activity with the countdown.
-
-### [watchOS](https://developer.apple.com/design/human-interface-guidelines/action-button#watchOS)
-
-In watchOS, a person can assign the Action button’s first press to drop a waypoint, start a dive, or begin a specific workout. Beyond a single button press, the Action button also supports secondary actions like marking a segment or transitioning to the next modality during a multi-part workout.
-
-**Consider offering a secondary function that supports or advances the primary action people choose.** People often use the Action button without looking at the screen, so a subsequent button press needs to flow logically from the first press, while also making sense in the current context. If your app supports workout or dive actions, consider designing a simple, intuitive secondary function that people can easily learn and remember. Consider carefully before you offer more than one secondary function, because doing so can increase people’s cognitive load and make your app seem harder to use.
-
-**Prefer using subsequent button presses to support additional functionality rather than to stop or conclude a function.** If you need to let people stop their main task — as opposed to pausing the current function — offer this option within your interface instead.
-
-**Pause the current function when people press the Action button and side button together.** The exception is in a diving app where pausing a dive may be dangerous to the diver, causing them to lose track of their depth or not understand how long they’ve been underwater. Unless pausing the current function results in a negative experience, be sure to meet people’s expectations by letting them pause their current activity when they press both buttons at the same time.
-
-## [Resources](https://developer.apple.com/design/human-interface-guidelines/action-button#Resources)
-
-#### [Related](https://developer.apple.com/design/human-interface-guidelines/action-button#Related)
-
-[Workouts](https://developer.apple.com/design/human-interface-guidelines/workouts)
-
-[Digital Crown](https://developer.apple.com/design/human-interface-guidelines/digital-crown)
-
-[App Shortcuts](https://developer.apple.com/design/human-interface-guidelines/app-shortcuts)
-
-[Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities)
-
-## [Change log](https://developer.apple.com/design/human-interface-guidelines/action-button#Change-log)
-
-Date| Changes  
----|---  
-September 12, 2023| Updated to include guidance for iOS.  
-September 14, 2022| New page.  
-  

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

@@ -1,261 +0,0 @@
----
-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/templates/vault/hig-components-menus/references/context-menus.md

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

@@ -1,84 +0,0 @@
----
-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)
-