@techwavedev/agi-agent-kit 1.5.2 → 1.6.0

package/templates/skills/extended/other/hig-components-layout/references/boxes.md

@@ -0,0 +1,48 @@
+---
+title: "Boxes | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/boxes
+
+# Boxes
+
+A box creates a visually distinct group of logically related information and components.
+
+![A stylized representation of a group of interface elements within a rounded rectangle. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/6e253271e9888e8d596d1d5b601d90f3/components-box-intro%402x.png)
+
+By default, a box uses a visible border or background color to separate its contents from the rest of the interface. A box can also include a title.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/boxes#Best-practices)
+
+**Prefer keeping a box relatively small in comparison with its containing view.** As a box’s size gets close to the size of the containing window or screen, it becomes less effective at communicating the separation of grouped content, and it can crowd other content.
+
+**Consider using padding and alignment to communicate additional grouping within a box.** A box’s border is a distinct visual element — adding nested boxes to define subgroups can make your interface feel busy and constrained.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/boxes#Content)
+
+**Provide a succinct introductory title if it helps clarify the box’s contents.** The appearance of a box helps people understand that its contents are related, but it might make sense to provide more detail about the relationship. Also, a title can help VoiceOver users predict the content they encounter within the box.
+
+**If you need a title, write a brief phrase that describes the contents.** Use sentence-style capitalization. Avoid ending punctuation unless you use a box in a settings pane, where you append a colon to the title.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/boxes#Platform-considerations)
+
+ _No additional considerations for visionOS. Not supported in tvOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/boxes#iOS-iPadOS)
+
+By default, iOS and iPadOS use the secondary and tertiary background [colors](https://developer.apple.com/design/human-interface-guidelines/color) in boxes.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/boxes#macOS)
+
+By default, macOS displays a box’s title above it.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/boxes#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/boxes#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/boxes#Developer-documentation)
+
+[`GroupBox`](https://developer.apple.com/documentation/SwiftUI/GroupBox) — SwiftUI
+
+[`NSBox`](https://developer.apple.com/documentation/AppKit/NSBox) — AppKit
+

package/templates/skills/extended/other/hig-components-layout/references/column-views.md

@@ -0,0 +1,44 @@
+---
+title: "Column views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/column-views
+
+# Column views
+
+A column view — also called a _browser_ — lets people view and navigate a data hierarchy using a series of vertical columns.
+
+![A stylized representation of three columns containing a list of folders, images, and file information. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/34ebf07677359428c45cbda0b9c1641e/components-column-view-intro%402x.png)
+
+Each column represents one level of the hierarchy and contains horizontal rows of data items. Within a column, any parent item that contains nested child items is marked with a triangle icon. When people select a parent, the next column displays its children. People can continue navigating in this way until they reach an item with no children, and can also navigate back up the hierarchy to explore other branches of data.
+
+Note
+
+If you need to manage the presentation of hierarchical content in your iPadOS or visionOS app, consider using a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/column-views#Best-practices)
+
+Consider using a column view when you have a deep data hierarchy in which people tend to navigate back and forth frequently between levels, and you don’t need the sorting capabilities that a [list or table](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) provides. For example, Finder offers a column view (in addition to icon, list, and gallery views) for navigating directory structures.
+
+**Show the root level of your data hierarchy in the first column.** People know they can quickly scroll back to the first column to begin navigating the hierarchy from the top again.
+
+**Consider showing information about the selected item when there are no nested items to display.** The Finder, for example, shows a preview of the selected item and information like the creation date, modification date, file type, and size.
+
+**Let people resize columns.** This is especially important if the names of some data items are too long to fit within the default column width.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/column-views#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/column-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/column-views#Related)
+
+[Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables)
+
+[Outline views](https://developer.apple.com/design/human-interface-guidelines/outline-views)
+
+[Split views](https://developer.apple.com/design/human-interface-guidelines/split-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/column-views#Developer-documentation)
+
+[`NSBrowser`](https://developer.apple.com/documentation/AppKit/NSBrowser) — AppKit
+

package/templates/skills/extended/other/hig-components-layout/references/lists-and-tables.md

@@ -0,0 +1,99 @@
+---
+title: "Lists and tables | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/lists-and-tables
+
+# Lists and tables
+
+Lists and tables present data in one or more columns of rows.
+
+![A stylized representation of a three-row table with header and footer 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/c3e26d2515ac05cae7aba2704f8640d6/components-lists-and-tables-intro%402x.png)
+
+A table or list can represent data that’s organized in groups or hierarchies, and it can support user interactions like selecting, adding, deleting, and reordering. Apps and games in all platforms can use tables to present content and options; many apps use lists to express an overall information hierarchy and help people navigate it. For example, iOS Settings uses a hierarchy of lists to help people choose options, and several apps — such as Mail in iPadOS and macOS — use a table within a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views).
+
+Sometimes, people need to work with complex data in a multicolumn table or a spreadsheet. Apps that offer productivity tasks often use a table to represent various characteristics or attributes of the data in separate, sortable columns.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Best-practices)
+
+**Prefer displaying text in a list or table.** A table can include any type of content, but the row-based format is especially well suited to making text easy to scan and read. If you have items that vary widely in size — or you need to display a large number of images — consider using a [collection](https://developer.apple.com/design/human-interface-guidelines/collections) instead.
+
+**Let people edit a table when it makes sense.** People appreciate being able to reorder a list, even if they can’t add or remove items. In iOS and iPadOS, people must enter an edit mode before they can select table items.
+
+**Provide appropriate feedback when people select a list item.** The feedback can vary depending on whether selecting the item reveals a new view or toggles the item’s state. In general, a table that helps people navigate through a hierarchy persistently highlights the selected row to clarify the path people are taking. In contrast, a table that lists options often highlights a row only briefly before adding an image — such as a checkmark — indicating that the item is selected.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Content)
+
+**Keep item text succinct so row content is comfortable to read.** Short, succinct text can help minimize truncation and wrapping, making text easier to read and scan. If each item consists of a large amount of text, consider alternatives that help you avoid displaying over-large table rows. For example, you could list item titles only, letting people choose an item to reveal its content in a detail view.
+
+**Consider ways to preserve readability of text that might otherwise get clipped or truncated.** When a table is narrow — for example, if people can vary its width — you want content to remain recognizable and easy to read. Sometimes, an ellipsis in the middle of text can make an item easier to distinguish because it preserves both the beginning and the end of the content.
+
+**Use descriptive column headings in a multicolumn table.** Use nouns or short noun phrases with [title-style capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64), and don’t add ending punctuation. If you don’t include a column heading in a single-column table view, use a label or a header to help people understand the context.
+
+## [Style](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Style)
+
+**Choose a table or list style that coordinates with your data and platform.** Some styles use visual details to help communicate grouping and hierarchy or to provide specific experiences. In iOS and iPadOS, for example, the grouped style uses headers, footers, and additional space to separate groups of data; the elliptical style available in watchOS makes items appear as if they’re rolling off a rounded surface as people scroll; and macOS defines a bordered style that uses alternating row backgrounds to help make large tables easier to use. For developer guidance, see [`ListStyle`](https://developer.apple.com/documentation/SwiftUI/ListStyle).
+
+**Choose a row style that fits the information you need to display.** For example, you might need to display a small image in the leading end of a row, followed by a brief explanatory label. Some platforms provide built-in row styles you can use to arrange content in list rows, such as the [`UIListContentConfiguration`](https://developer.apple.com/documentation/UIKit/UIListContentConfiguration-swift.struct) API you can use to lay out content in a list’s rows, headers, and footers in iOS, iPadOS, and tvOS.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Platform-considerations)
+
+### [iOS, iPadOS, visionOS](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#iOS-iPadOS-visionOS)
+
+**Use an info button only to reveal more information about a row’s content.** An info button — called a _detail disclosure button_ when it appears in a list row — doesn’t support navigation through a hierarchical table or list. If you need to let people drill into a list or table row’s subviews, use a disclosure indicator accessory control. For developer guidance, see [`UITableViewCell.AccessoryType.disclosureIndicator`](https://developer.apple.com/documentation/UIKit/UITableViewCell/AccessoryType-swift.enum/disclosureIndicator).
+
+![An illustration of a grouped list of rows. Each list item includes an info button at the trailing end of the row.](https://docs-assets.developer.apple.com/published/fd301d26835e0341b95eaa2027f200f2/info-button-in-list%402x.png)An info button shows details about a list item; it doesn’t support navigation.
+
+![An illustration of a grouped list of rows. Each list item includes a right-pointing chevron at the trailing end of the row.](https://docs-assets.developer.apple.com/published/dcb3678fe458846713b03756ab5e1a28/disclosure-indicator-in-list%402x.png)A disclosure indicator reveals the next level in a hierarchy; it doesn’t show details about the item.
+
+**Avoid adding an index to a table that displays controls — like disclosure indicators — in the trailing ends of its rows.** An _index_ typically consists of the letters in an alphabet, displayed vertically at the trailing side of a list. People can jump to a specific section in the list by choosing the index letter that maps to it. Because both the index and elements like disclosure indicators appear on the trailing side of a list, it can be difficult for people to use one element without activating the other.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#macOS)
+
+**When it provides value, let people click a column heading to sort a table view based on that column**. If people click the heading of a column that’s already sorted, re-sort the data in the opposite direction.
+
+**Let people resize columns.** Data displayed in a table view often varies in width. People appreciate resizing columns to help them concentrate on different areas or reveal clipped data.
+
+**Consider using alternating row colors in a multicolumn table.** Alternating colors can help people track row values across columns, especially in a wide table.
+
+**Use an outline view instead of a table view to present hierarchical data.** An [outline view](https://developer.apple.com/design/human-interface-guidelines/outline-views) looks like a table view, but includes disclosure triangles for exposing nested levels of data. For example, an outline view might display folders and the items they contain.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#tvOS)
+
+**Confirm that images near a table still look good as each row highlights and slightly increases in size when it becomes focused.** A focused row’s corners can also become rounded, which may affect the appearance of images on either side of it. Account for this effect as you prepare images, and don’t add your own masks to round the corners.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#watchOS)
+
+**When possible, limit the number of rows.** Short lists are easier for people to scan, but sometimes people expect a long list of items. For example, if people subscribe to a large number of podcasts, they might think something’s wrong if they can’t view all their items. You can help make a long list more manageable by listing the most relevant items and providing a way for people to view more.
+
+**Constrain the length of detail views if you want to support vertical page-based navigation.** People use vertical page-based navigation to swipe vertically among the detail items of different list rows. Navigating in this way saves time because people don’t need to return to the list to tap a new detail item, but it works only when detail views are short. If your detail views scroll, people won’t be able to use vertical page-based navigation to swipe among them.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Related)
+
+[Collections](https://developer.apple.com/design/human-interface-guidelines/collections)
+
+[Outline views](https://developer.apple.com/design/human-interface-guidelines/outline-views)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Developer-documentation)
+
+[`List`](https://developer.apple.com/documentation/SwiftUI/List) — SwiftUI
+
+[Tables](https://developer.apple.com/documentation/SwiftUI/Tables) — SwiftUI
+
+[`UITableView`](https://developer.apple.com/documentation/UIKit/UITableView) — UIKit
+
+[`NSTableView`](https://developer.apple.com/documentation/AppKit/NSTableView) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#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)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+June 5, 2023| Updated guidance to reflect changes in watchOS 10.  
+  

package/templates/skills/extended/other/hig-components-layout/references/ornaments.md

@@ -0,0 +1,56 @@
+---
+title: "Ornaments | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/ornaments
+
+# Ornaments
+
+In visionOS, an ornament presents controls and information related to a window, without crowding or obscuring the window’s contents.
+
+![A stylized representation of an ornament at the bottom of a window shown on top of a grid that suggests the canvas of a design tool. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/a9012c3e7b1c5d47a4788aefd7a5b48c/components-ornaments-intro%402x.png)
+
+An ornament floats in a plane that’s parallel to its associated window and slightly in front of it along the z-axis. If the associated window moves, the ornament moves with it, maintaining its relative position; if the window’s contents scroll, the controls or information in the ornament remain unchanged.
+
+Ornaments can appear on any edge of a window and can contain UI components like buttons, segmented controls, and other views. The system uses ornaments to create and manage components like [toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars), [tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars), and video playback controls; you can use an ornament to create a custom component.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/ornaments#Best-practices)
+
+**Consider using an ornament to present frequently needed controls or information in a consistent location that doesn’t clutter the window.** Because an ornament stays close to its window, people always know where to find it. For example, Music uses an ornament to offer Now Playing controls, ensuring that these controls remain in a predictable location that’s easy to find.
+
+**In general, keep an ornament visible.** It can make sense to hide an ornament when people dive into a window’s content — for example, when they watch a video or view a photo — but in most cases, people appreciate having consistent access to an ornament’s controls.
+
+**If you need to display multiple ornaments, prioritize the overall visual balance of the window.** Ornaments help elevate important actions, but they can sometimes distract from your content. When necessary, consider constraining the total number of ornaments to avoid increasing a window’s visual weight and making your app feel more complicated. If you decide to remove an ornament, you can relocate its elements into the main window.
+
+**Aim to keep an ornament’s width the same or narrower than the width of the associated window.** If an ornament is wider than its window, it can interfere with a tab bar or other vertical content on the window’s side.
+
+**Consider using borderless buttons in an ornament.** By default, an ornament’s background is [glass](https://developer.apple.com/design/human-interface-guidelines/materials#visionOS), so if you place a button directly on the background, it may not need a visible border. When people look at a borderless button in an ornament, the system automatically applies the hover affect to it (for guidance, see [Eyes](https://developer.apple.com/design/human-interface-guidelines/eyes)).
+
+**Use system-provided toolbars and tab bars unless you need to create custom components.** In visionOS, toolbars and tab bars automatically appear as ornaments, so you don’t need to use an ornament to create these components. For developer guidance, see [Toolbars](https://developer.apple.com/documentation/SwiftUI/Toolbars) and [`TabView`](https://developer.apple.com/documentation/SwiftUI/TabView).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/ornaments#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, macOS, tvOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/ornaments#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/ornaments#Related)
+
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+[Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/ornaments#Developer-documentation)
+
+[`ornament(visibility:attachmentAnchor:contentAlignment:ornament:)`](https://developer.apple.com/documentation/SwiftUI/View/ornament\(visibility:attachmentAnchor:contentAlignment:ornament:\)) — SwiftUI
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/ornaments#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/38E4EE32-29B5-4478-B8B6-35B8ACA67B16/8130_wide_250x141_1x.jpg) Design for spatial user interfaces ](https://developer.apple.com/videos/play/wwdc2023/10076)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/ornaments#Change-log)
+
+Date| Changes  
+---|---  
+February 2, 2024| Added guidance on using multiple ornaments.  
+December 5, 2023| Removed a statement about using ornaments to present supplementary items.  
+June 21, 2023| New page.  
+  

package/templates/skills/extended/other/hig-components-layout/references/outline-views.md

@@ -0,0 +1,64 @@
+---
+title: "Outline views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/outline-views
+
+# Outline views
+
+An outline view presents hierarchical data in a scrolling list of cells that are organized into columns and rows.
+
+![A stylized representation of a list of folders and images, displayed in an outline view containing four columns: \[Name\], \[Date Modified\], \[Size\], and \[Kind\]. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/30462b13b59c89c7ba9e142a2fcef05b/components-outline-view-intro%402x.png)
+
+An outline view includes at least one column that contains primary hierarchical data, such as a set of parent containers and their children. You can add columns, as needed, to display attributes that supplement the primary data; for example, sizes and modification dates. Parent containers have disclosure triangles that expand to reveal their children.
+
+Finder windows offer an outline view for navigating the file system.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/outline-views#Best-practices)
+
+Outline views work well to display text-based content and often appear in the leading side of a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views), with related content on the opposite side.
+
+**Use a table instead of an outline view to present data that’s not hierarchical.** For guidance, see [Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables).
+
+**Expose data hierarchy in the first column only.** Other columns can display attributes that apply to the hierarchical data in the primary column.
+
+**Use descriptive column headings to provide context.** Use nouns or short noun phrases with [title-style capitalization](https://help.apple.com/applestyleguide/#/apsgb744e4a3?sub=apdca93e113f1d64) and no punctuation; in particular, avoid adding a trailing colon. Always provide column headings in a multi-column outline view. If you don’t include a column heading in a single-column outline view, use a label or other means to make sure there’s enough context.
+
+**Consider letting people click column headings to sort an outline view.** In a sortable outline view, people can click a column heading to perform an ascending or descending sort based on that column. You can implement additional sorting based on secondary columns behind the scenes, if necessary. If people click the primary column heading, sorting occurs at each hierarchy level. For example, in the Finder, all top-level folders are sorted, then the items within each folder are sorted. If people click the heading of a column that’s already sorted, the folders and their contents are sorted again in the opposite direction.
+
+**Let people resize columns.** Data displayed in an outline view often varies in width. It’s important to let people adjust column width as needed to reveal data that’s wider than the column.
+
+**Make it easy for people to expand or collapse nested containers.** For example, clicking a disclosure triangle for a folder in a Finder window expands only that folder. However, Option-clicking the disclosure triangle expands all of its subfolders.
+
+**Retain people’s expansion choices.** If people expand various levels of an outline view to reach a specific item, store the state so you can display it again the next time. This way, people won’t need to navigate back to the same place again.
+
+**Consider using alternating row colors in multi-column outline views.** Alternating colors can make it easier for people to track row values across columns, especially in wide outline views.
+
+**Let people edit data if it makes sense in your app.** In an editable outline view cell, people expect to be able to single-click a cell to edit its contents. Note that a cell can respond differently to a double click. For example, an outline view listing files might let people single-click a file’s name to edit it, but double-click a file’s name to open the file. You can also let people reorder, add, and remove rows if it would be useful.
+
+**Consider using a centered ellipsis to truncate cell text instead of clipping it.** An ellipsis in the middle preserves the beginning and end of the cell text, which can make the content more distinct and recognizable than clipped text.
+
+**Consider offering a search field to help people find values quickly in a lengthy outline view.** Windows with an outline view as the primary feature often include a search field in the toolbar. For guidance, see [Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/outline-views#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/outline-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/outline-views#Related)
+
+[Column views](https://developer.apple.com/design/human-interface-guidelines/column-views)
+
+[Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables)
+
+[Split views](https://developer.apple.com/design/human-interface-guidelines/split-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/outline-views#Developer-documentation)
+
+[`OutlineGroup`](https://developer.apple.com/documentation/SwiftUI/OutlineGroup) — SwiftUI
+
+[`NSOutlineView`](https://developer.apple.com/documentation/AppKit/NSOutlineView) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/outline-views#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/templates/skills/extended/other/hig-components-layout/references/panels.md

@@ -0,0 +1,75 @@
+---
+title: "Panels | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/panels
+
+# Panels
+
+In a macOS app, a panel typically floats above other open windows providing supplementary controls, options, or information related to the active window or current selection.
+
+![A stylized representation of a panel floating above a window. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/37f7c9e6dd4c635ccbae68b50200a74c/components-panel-intro%402x.png)
+
+In general, a panel has a less prominent appearance than an app’s [main window](https://developer.apple.com/design/human-interface-guidelines/windows#macOS-window-states). When the situation calls for it, a panel can also use a dark, translucent style to support a heads-up display (or _HUD_) experience.
+
+When your app runs in other platforms, consider using a modal view to present supplementary content that’s relevant to the current task or selection. For guidance, see [Modality](https://developer.apple.com/design/human-interface-guidelines/modality).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/panels#Best-practices)
+
+**Use a panel to give people quick access to important controls or information related to the content they’re working with.** For example, you might use a panel to provide controls or settings that affect the selected item in the active document or window.
+
+**Consider using a panel to present inspector functionality.** An _inspector_ displays the details of the currently selected item, automatically updating its contents when the item changes or when people select a new item. In contrast, if you need to present an _Info_ window — which always maintains the same contents, even when the selected item changes — use a regular window, not a panel. Depending on the layout of your app, you might also consider using a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views) pane to present an inspector.
+
+**Prefer simple adjustment controls in a panel.** As much as possible, avoid including controls that require typing text or selecting items to act upon because these actions can require multiple steps. Instead, consider using controls like sliders and steppers because these components can give people more direct control.
+
+**Write a brief title that describes the panel’s purpose.** Because a panel often floats above other open windows in your app, it needs a title bar so people can position it where they want. Create a short title using a noun — or a noun phrase with [title-style capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64) — that can help people recognize the panel onscreen. For example, macOS provides familiar panels titled “Fonts” and “Colors,” and many apps use the title “Inspector.”
+
+**Show and hide panels appropriately.** When your app becomes active, bring all of its open panels to the front, regardless of which window was active when the panel opened. When your app is inactive, hide all of its panels.
+
+**Avoid including panels in the Window menu’s documents list.** It’s fine to include commands for showing or hiding panels in the [Window menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Window-menu), but panels aren’t documents or standard app windows, and they don’t belong in the Window menu’s list.
+
+**In general, avoid making a panel’s minimize button available.** People don’t usually need to minimize a panel, because it displays only when needed and disappears when the app is inactive.
+
+**Refer to panels by title in your interface and in help documentation.** In menus, use the panel’s title without including the term _panel_ : for example, “Show Fonts,” “Show Colors,” and “Show Inspector.” In help documentation, it can be confusing to introduce “panel” as a different type of window, so it’s generally best to refer to a panel by its title or — when it adds clarity — by appending _window_ to the title. For example, the title “Inspector” often supplies enough context to stand on its own, whereas it can be clearer to use “Fonts window” and “Colors window” instead of just “Fonts” and “Colors.”
+
+## [HUD-style panels](https://developer.apple.com/design/human-interface-guidelines/panels#HUD-style-panels)
+
+A HUD-style panel serves the same function as a standard panel, but its appearance is darker and translucent. HUDs work well in apps that present highly visual content or that provide an immersive experience, such as media editing or a full-screen slide show. For example, QuickTime Player uses a HUD to display inspector information without obstructing too much content.
+
+![A screenshot of a translucent HUD panel, used to display inspector information for a movie file, including the filename, format, frames per second, data rate, and the frame size of the movie content.](https://docs-assets.developer.apple.com/published/f3fccb3f4ad6963af1310c8f98c5a0f7/hud-style-panel%402x.png)
+
+**Prefer standard panels.** People can be distracted or confused by a HUD when there’s no logical reason for its presence. Also, a HUD might not match the current appearance setting. In general, use a HUD only:
+
+  * In a media-oriented app that presents movies, photos, or slides
+
+  * When a standard panel would obscure essential content
+
+  * When you don’t need to include controls — with the exception of the disclosure triangle, most system-provided controls don’t match a HUD’s appearance.
+
+
+
+
+**Maintain one panel style when your app switches modes.** For example, if you use a HUD when your app is in full-screen mode, prefer maintaining the HUD style when people take your app out of full-screen mode.
+
+**Use color sparingly in HUDs.** Too much color in the dark appearance of a HUD can be distracting. Often, you need only small amounts of high-contrast color to highlight important information in a HUD.
+
+**Keep HUDs small.** HUDs are designed to be unobtrusively useful, so letting them grow too large defeats their primary purpose. Don’t let a HUD obscure the content it adjusts, and make sure it doesn’t compete with the content for people’s attention.
+
+For developer guidance, see [`hudWindow`](https://developer.apple.com/documentation/AppKit/NSWindow/StyleMask-swift.struct/hudWindow).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/panels#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/panels#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/panels#Related)
+
+[Windows](https://developer.apple.com/design/human-interface-guidelines/windows)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/panels#Developer-documentation)
+
+[`NSPanel`](https://developer.apple.com/documentation/AppKit/NSPanel) — AppKit
+
+[`hudWindow`](https://developer.apple.com/documentation/AppKit/NSWindow/StyleMask-swift.struct/hudWindow) — AppKit
+

package/templates/skills/extended/other/hig-components-layout/references/scroll-views.md

@@ -0,0 +1,123 @@
+---
+title: "Scroll views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/scroll-views
+
+# Scroll views
+
+A scroll view lets people view content that’s larger than the view’s boundaries by moving the content vertically or horizontally.
+
+![A stylized representation of a scrollable image view. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/395072e6a9ec2890d242c1d967a7cbe4/components-scroll-view-intro%402x.png)
+
+The scroll view itself has no appearance, but it can display a translucent _scroll indicator_ that typically appears after people begin scrolling the view’s content. Although the appearance and behavior of scroll indicators can vary per platform, all indicators provide visual feedback about the scrolling action. For example, in iOS, iPadOS, macOS, visionOS, and watchOS, the indicator shows whether the currently visible content is near the beginning, middle, or end of the view.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Best-practices)
+
+**Support default scrolling gestures and keyboard shortcuts.** People are accustomed to the systemwide scrolling behavior and expect it to work everywhere. If you build custom scrolling for a view, make sure your scroll indicators use the elastic behavior that people expect.
+
+**Make it apparent when content is scrollable.** Because scroll indicators aren’t always visible, it can be helpful to make it obvious when content extends beyond the view. For example, displaying partial content at the edge of a view indicates that there’s more content in that direction. Although most people immediately try scrolling a view to discover if additional content is available, it’s considerate to draw their attention to it.
+
+**Avoid putting a scroll view inside another scroll view with the same orientation.** Nesting scroll views that have the same orientation can create an unpredictable interface that’s difficult to control. It’s alright to place a horizontal scroll view inside a vertical scroll view (or vice versa), however.
+
+**Consider supporting page-by-page scrolling if it makes sense for your content.** In some situations, people appreciate scrolling by a fixed amount of content per interaction instead of scrolling continuously. On most platforms, you can define the size of such a _page_ — typically the current height or width of the view — and define an interaction that scrolls one page at a time. To help maintain context during page-by-page scrolling, you can define a unit of overlap, such as a line of text, a row of glyphs, or part of a picture, and subtract the unit from the page size. For developer guidance, see [`PagingScrollTargetBehavior`](https://developer.apple.com/documentation/SwiftUI/PagingScrollTargetBehavior).
+
+**In some cases, scroll automatically to help people find their place.** Although people initiate almost all scrolling, automatic scrolling can be helpful when relevant content is no longer in view, such as when:
+
+  * Your app performs an operation that selects content or places the insertion point in an area that’s currently hidden. For example, when your app locates text that people are searching for, scroll the content to bring the new selection into view.
+
+  * People start entering information in a location that’s not currently visible. For example, if the insertion point is on one page and people navigate to another page, scroll back to the insertion point as soon as they begin to enter text.
+
+  * The pointer moves past the edge of the view while people are making a selection. In this case, follow the pointer by scrolling in the direction it moves.
+
+  * People select something and scroll to a new location before acting on the selection. In this case, scroll until the selection is in view before performing the operation.
+
+
+
+
+In all cases, automatically scroll the content only as much as necessary to help people retain context. For example, if part of a selection is visible, you don’t need to scroll the entire selection into view.
+
+**If you support zoom, set appropriate maximum and minimum scale values.** For example, zooming in on text until a single character fills the screen doesn’t make sense in most situations.
+
+## [Scroll edge effects](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Scroll-edge-effects)
+
+In iOS, iPadOS, and macOS, a _scroll edge effect_ is a variable blur that provides a transition between a content area and an area with [Liquid Glass](https://developer.apple.com/design/human-interface-guidelines/materials#Liquid-Glass) controls, such as [toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars). In most cases, the system applies a scroll edge effect automatically when a pinned element overlaps with scrolling content. If you use custom controls or layouts, the effect might not appear, and you may need to add it manually. For developer guidance, see [`ScrollEdgeEffectStyle`](https://developer.apple.com/documentation/SwiftUI/ScrollEdgeEffectStyle) and [`UIScrollEdgeEffect`](https://developer.apple.com/documentation/UIKit/UIScrollEdgeEffect).
+
+There are two styles of scroll edge effect: soft and hard.
+
+  * Use a [`soft`](https://developer.apple.com/documentation/SwiftUI/ScrollEdgeEffectStyle/soft) edge effect in most cases, especially in iOS and iPadOS, to provide a subtle transition that works well for toolbars and interactive elements like buttons.
+
+  * Use a [`hard`](https://developer.apple.com/documentation/SwiftUI/ScrollEdgeEffectStyle/hard) edge effect primarily in macOS for a stronger, more opaque boundary that’s ideal for interactive text, backless controls, or pinned table headers that need extra clarity.
+
+
+
+
+**Only use a scroll edge effect when a scroll view is adjacent to floating interface elements.** Scroll edge effects aren’t decorative. They don’t block or darken like overlays; they exist to clarify where controls and content meet.
+
+**Apply one scroll edge effect per view.** In split view layouts on iPad and Mac, each pane can have its own scroll edge effect; in this case, keep them consistent in height to maintain alignment.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Platform-considerations)
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/scroll-views#iOS-iPadOS)
+
+**Consider showing a page control when a scroll view is in page-by-page mode.** [Page controls](https://developer.apple.com/design/human-interface-guidelines/page-controls) show how many pages, screens, or other chunks of content are available and indicates which one is currently visible. For example, Weather uses a page control to indicate movement between people’s saved locations. If you show a page control with a scroll view, don’t show the scrolling indicator on the same axis to avoid confusing people with redundant controls.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/scroll-views#macOS)
+
+In macOS, a _scroll indicator_ is commonly called a _scroll bar_.
+
+**If necessary, use small or mini scroll bars in a panel.** When space is tight, you can use smaller scroll bars in panels that need to coexist with other windows. Be sure to use the same size for all controls in such a panel.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/scroll-views#tvOS)
+
+Views in tvOS can scroll, but they aren’t treated as distinct objects with scroll indicators. Instead, when content exceeds the size of the screen, the system automatically scrolls the interface to keep focused items visible.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/scroll-views#visionOS)
+
+In visionOS, the scroll indicator has a small, fixed size to help communicate that people can scroll efficiently without making large movements. To make it easy to find, the scroll indicator always appears in a predictable location with respect to the window: vertically centered at the trailing edge during vertical scrolling and horizontally centered at the window’s bottom edge during horizontal scrolling.
+
+When people begin swiping content in the direction they want it to scroll, the scroll indicator appears at the window’s edge, visually reinforcing the effect of their gesture and providing feedback about the content’s current position and overall length. When people look at the scroll indicator and begin a drag gesture, the indicator enables a jog bar experience that lets people manipulate the scrolling speed instead of the content’s position. In this experience, the scroll indicator reveals tick marks that speed up or slow down as people make small adjustments to their gesture, providing visual feedback that helps people precisely control scrolling acceleration.
+
+Video with custom controls. 
+
+Content description: A recording showing a scroll indicator on a long page in the Notes app. As the viewer drags the page quickly, the indicator shows tick marks that match the scrolling speed. 
+
+Play 
+
+**If necessary, account for the size of the scroll indicator.** Although the indicator’s overall size is small, it’s a little thicker than the same component in iOS. If your content uses tight margins, consider increasing them to prevent the scroll indicator from overlapping the content.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/scroll-views#watchOS)
+
+**Prefer vertically scrolling content.** People are accustomed to using the Digital Crown to navigate to and within apps on Apple Watch. If your app contains a single list or content view, rotating the Digital Crown scrolls vertically when your app’s content is taller than the height of the display.
+
+**Use tab views to provide page-by-page scrolling.** watchOS displays tab views as pages. If you place tab views in a vertical stack, people can rotate the Digital Crown to move vertically through full-screen pages of content. In this scenario, the system displays a page indicator next to the Digital Crown that shows people where they are in the content, both within the current page and within a set of pages. For guidance, see [Tab views](https://developer.apple.com/design/human-interface-guidelines/tab-views).
+
+**When displaying paged content, consider limiting the content of an individual page to a single screen height.** Embracing this constraint clarifies the purpose of each page, helping you create a more glanceable design. However, if your app has long pages, people can still use the Digital Crown both to navigate between shorter pages and to scroll content in a longer page because the page indicator expands into a scroll indicator when necessary. Use variable-height pages judiciously and place them after fixed-height pages when possible.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Related)
+
+[Page controls](https://developer.apple.com/design/human-interface-guidelines/page-controls)
+
+[Gestures](https://developer.apple.com/design/human-interface-guidelines/gestures)
+
+[Pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Developer-documentation)
+
+[`ScrollView`](https://developer.apple.com/documentation/SwiftUI/ScrollView)
+
+[`UIScrollView`](https://developer.apple.com/documentation/UIKit/UIScrollView)
+
+[`NSScrollView`](https://developer.apple.com/documentation/AppKit/NSScrollView)
+
+[`WKPageOrientation`](https://developer.apple.com/documentation/WatchKit/WKPageOrientation)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/scroll-views#Change-log)
+
+Date| Changes  
+---|---  
+July 28, 2025| Added guidance for scroll edge effects.  
+February 2, 2024| Added artwork showing the behavior of the visionOS scroll indicator.  
+December 5, 2023| Described the visionOS scroll indicator and added guidance for integrating it with window layout.  
+June 5, 2023| Updated guidance for using scroll views in watchOS.  
+