@ngxtm/devkit 3.15.0 → 3.16.0

package/skills/hig-components-dialogs/references/sheets.md

@@ -0,0 +1,157 @@
+---
+title: "Sheets | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/sheets
+
+# Sheets
+
+A sheet helps people perform a scoped task that’s closely related to their current context.
+
+![A stylized representation of a sheet extending down from the top of 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/357ff0b017e9241da82888bd3aec4372/components-sheet-intro%402x.png)
+
+By default, a sheet is _modal_ , presenting a targeted experience that prevents people from interacting with the parent view until they dismiss the sheet (for more on modal presentation, see [Modality](https://developer.apple.com/design/human-interface-guidelines/modality)). A modal sheet is useful for requesting specific information from people or presenting a simple task that they can complete before returning to the parent view. For example, a sheet might let people supply information needed to complete an action, such as attaching a file, choosing the location for a move or save, or specifying the format for a selection.
+
+In macOS, visionOS, and watchOS, a sheet is always modal, but in iOS and iPadOS, a sheet can also be nonmodal. When a nonmodal sheet is onscreen, people use its functionality to directly affect the current task in the parent view without dismissing the sheet. For example, Notes on iPhone and iPad uses a nonmodal sheet to help people apply different formatting to various text selections as they edit a note.
+
+![A screenshot of an in-progress note on iPhone. Several words are selected and highlighted. In the bottom half of the screen, the format sheet shows that the selected words use the regular body font.](https://docs-assets.developer.apple.com/published/56830eea369c54ce82f6867a0907f3f3/sheets-nonmodal-notes-text-regular%402x.png)
+
+The Notes format sheet lets people apply formatting to selected text in the editing view.
+
+![A screenshot of the same in-progress note on iPhone. Different words are selected and highlighted. The format sheet shows that the selected words use the body font in italics.](https://docs-assets.developer.apple.com/published/f7b427fb2d880e16df4ed1025a43b47c/sheets-nonmodal-notes-text-italic%402x.png)
+
+Because the sheet is nonmodal, people can make additional text selections without dismissing the sheet.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/sheets#Best-practices)
+
+**Use a sheet to present simple content or tasks.** A sheet allows some of the parent view to remain visible, helping people retain their original context as they interact with the sheet.
+
+**For complex or prolonged user flows, consider alternatives to sheets.** For example, iOS and iPadOS offer a full-screen style of modal view that can work well to display content like videos, photos, or camera views or to help people perform multistep tasks like document or photo editing. (For developer guidance, see [`UIModalPresentationStyle.fullScreen`](https://developer.apple.com/documentation/UIKit/UIModalPresentationStyle/fullScreen).) In a macOS experience, you might want to open a new window or let people enter full-screen mode instead of using a sheet. For example, a self-contained task like editing a document tends to work well in a separate window, whereas [going full screen](https://developer.apple.com/design/human-interface-guidelines/going-full-screen) can help people view media. In visionOS, you can give people a way to transition your app to a Full Space where they can dive into content or a task; for guidance, see [Immersive experiences](https://developer.apple.com/design/human-interface-guidelines/immersive-experiences).
+
+**Display only one sheet at a time from the main interface.** When people close a sheet, they expect to return to the parent view or window. If closing a sheet takes people back to another sheet, they can lose track of where they are in your app. If something people do within a sheet results in another sheet appearing, close the first sheet before displaying the new one. If necessary, you can display the first sheet again after people dismiss the second one.
+
+**Use a nonmodal view when you want to present supplementary items that affect the main task in the parent view.** To give people access to information and actions they need while continuing to interact with the main window, consider using a [split view](https://developer.apple.com/design/human-interface-guidelines/split-views) in visionOS or a [panel](https://developer.apple.com/design/human-interface-guidelines/panels) in macOS; in iOS and iPadOS, you can use a nonmodal sheet for this workflow. For guidance, see [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/sheets#iOS-iPadOS).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/sheets#Platform-considerations)
+
+ _No additional considerations for tvOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/sheets#iOS-iPadOS)
+
+A resizable sheet expands when people scroll its contents or drag the _grabber_ , which is a small horizontal indicator that can appear at the top edge of a sheet. Sheets resize according to their _detents_ , which are particular heights at which a sheet naturally rests. Designed for iPhone, detents specify particular heights at which a sheet naturally rests. The system defines two detents: _large_ is the height of a fully expanded sheet and _medium_ is about half of the fully expanded height.
+
+![An illustration showing an iPhone screen in portrait orientation containing a solid rounded rectangle that occupies almost all of the screen, representing a full-screen sheet. A rounded close button appears in the upper-left corner of the sheet.](https://docs-assets.developer.apple.com/published/c2a600adb5237892585d71d2ae61c9a6/sheets-large-detent%402x.png)
+
+Large detent
+
+![An illustration showing an iPhone screen in portrait orientation containing a solid rounded rectangle that occupies half of the screen, representing a half-screen sheet. A rounded close button appears in the upper-left corner of the sheet.](https://docs-assets.developer.apple.com/published/413ac0d4cf462891f2ba9d0cd4bb01f1/sheets-medium-detent%402x.png)
+
+Medium detent
+
+Sheets automatically support the large detent. Adding the medium detent allows the sheet to rest at both heights, whereas specifying only medium prevents the sheet from expanding to full height. For developer guidance, see [`detents`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController/detents).
+
+**In an iPhone app, consider supporting the medium detent to allow progressive disclosure of the sheet’s content.** For example, a share sheet displays the most relevant items within the medium detent, where they’re visible without resizing. To view more items, people can scroll or expand the sheet. In contrast, you might not want to support the medium detent if a sheet’s content is more useful when it displays at full height. For example, the compose sheets in Messages and Mail display only at full height to give people enough room to create content.
+
+**Include a grabber in a resizable sheet.** A grabber shows people that they can drag the sheet to resize it; they can also tap it to cycle through the detents. In addition to providing a visual indicator of resizability, a grabber also works with VoiceOver so people can resize the sheet without seeing the screen. For developer guidance, see [`prefersGrabberVisible`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController/prefersGrabberVisible).
+
+**Support swiping to dismiss a sheet.** People expect to swipe vertically to dismiss a sheet instead of tapping a dismiss button. If people have unsaved changes in the sheet when they begin swiping to dismiss it, use an action sheet to let them confirm their action.
+
+**Position Done and Cancel buttons as people expect.** Typically, a Done or Dismiss button belongs in a sheet’s top-right corner in a left-to-right layout. The Cancel button belongs in a sheet’s top-left corner.
+
+The exception to this is for sheets with additional subviews, where the Cancel button belongs in the top-right; this provides room for the Back button in the top-left on pages after the first. At the end of the navigation flow, replace the Cancel button with the Done button.
+
+![An illustration of the top half of a sheet on iPhone. A Cancel button appears in the top-left corner of the view.](https://docs-assets.developer.apple.com/published/4c0ea03add08b05592c51ed58ebb79f1/sheets-close-button-placement-no-back%402x.png)
+
+Placement of the Cancel button when it appears by itself
+
+![An illustration of the top half of a sheet on iPhone. A Back button appears in the top-left corner of the view, and a Cancel button appears in the top-right corner.](https://docs-assets.developer.apple.com/published/4325d8e5db78c585b01a7137e34189c7/sheets-close-button-placement-with-back%402x.png)
+
+Placement of the Cancel button when it appears as part of a multi-step flow
+
+**Prefer using the page or form sheet presentation styles in an iPadOS app.** Each style uses a default size for the sheet, centering its content on top of a dimmed background view and providing a consistent experience. For developer guidance, see [`UIModalPresentationStyle`](https://developer.apple.com/documentation/UIKit/UIModalPresentationStyle).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/sheets#macOS)
+
+In macOS, a sheet is a cardlike view with rounded corners that floats on top of its parent window. The parent window is dimmed while the sheet is onscreen, signaling that people can’t interact with it until they dismiss the sheet. However, people expect to interact with other app windows before dismissing a sheet.
+
+![A screenshot of the Notes app, with the What's New in Notes sheet centered on top of a dimmed Notes document in the background.](https://docs-assets.developer.apple.com/published/582e02d0df9b4a07dea002053f9ec6ea/sheets-macos-notes%402x.png)
+
+**Present a sheet in a reasonable default size.** People don’t generally expect to resize sheets, so it’s important to use a size that’s appropriate for the content you display. In some cases, however, people appreciate a resizable sheet — such as when they need to expand the contents for a clearer view — so it’s a good idea to support resizing.
+
+**Let people interact with other app windows without first dismissing a sheet.** When a sheet opens, you bring its parent window to the front — if the parent window is a document window, you also bring forward its modeless document-related panels. When people want to interact with other windows in your app, make sure they can bring those windows forward even if they haven’t dismissed the sheet yet.
+
+**Position a sheet’s dismiss buttons as people expect.** People expect to find all buttons that dismiss a sheet — including Done, OK, and Cancel — at the bottom of the view, in the trailing corner.
+
+**Use a panel instead of a sheet if people need to repeatedly provide input and observe results.** A find and replace panel, for example, might let people initiate replacements individually, so they can observe the result of each search for correctness. For guidance, see [Panels](https://developer.apple.com/design/human-interface-guidelines/panels).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/sheets#visionOS)
+
+While a sheet is visible in a visionOS app, it floats in front of its parent window, dimming it, and becoming the target of people’s interactions with the app.
+
+Video with custom controls. 
+
+Content description: A recording showing a sheet opening above a blank window in visionOS. 
+
+Play 
+
+**Avoid displaying a sheet that emerges from the bottom edge of a window.** To help people view the sheet, prefer centering it in their [field of view](https://developer.apple.com/design/human-interface-guidelines/spatial-layout#Field-of-view).
+
+**Present a sheet in a default size that helps people retain their context.** Avoid displaying a sheet that covers most or all of its window, but consider letting people resize the sheet if they want.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/sheets#watchOS)
+
+In watchOS, a sheet is a full-screen view that slides over your app’s current content. The sheet is semitransparent to help maintain the current context, but the system applies a material to the background that blurs and desaturates the covered content.
+
+![A screenshot of a sheet with a primary Action button and a default cancel button on Apple Watch.](https://docs-assets.developer.apple.com/published/fcdad96a098bea9c7b98a114403e46f2/sheets-watch-overlay%402x.png)
+
+**Use a sheet only when your modal task requires a custom title or custom content presentation.** If you need to give people important information or present a set of choices, consider using an [alert](https://developer.apple.com/design/human-interface-guidelines/alerts) or [action sheet](https://developer.apple.com/design/human-interface-guidelines/action-sheets).
+
+**Keep sheet interactions brief and occasional.** Use a sheet only as a temporary interruption to the current workflow, and only to facilitate an important task. Avoid using a sheet to help people navigate your app’s content.
+
+**Change the default label of the dismiss control only if it makes sense in your app.** By default, the sheet displays a round Cancel button in the upper left corner. Use this button when the sheet lets people make changes to the app’s behavior or to their data. If your sheet simply presents information without enabling a task, use the standard Done button instead. You can use a [toolbar](https://developer.apple.com/design/human-interface-guidelines/toolbars) to display multiple buttons.
+
+![A screenshot of a watch displaying a sheet with the standard check mark Done button on Apple Watch.](https://docs-assets.developer.apple.com/published/bc70ac8a01bd110befa02132e9f53672/sheets-watch-custom%402x.png)
+
+The standard Done button
+
+**If you change the default label, prefer using SF Symbols to represent the action.** Avoid using a label that might mislead people into thinking that the sheet is part of a hierarchical navigation interface. Also, if the text in the top-leading corner looks like a page or app title, people won’t know how to dismiss the sheet. For guidance, see [Standard icons](https://developer.apple.com/design/human-interface-guidelines/icons#Standard-icons).
+
+![A screenshot that shows a top toolbar with the default Cancel button at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/4b2b3901392b3a2101bf98fbee0b7809/modal-sheet-watchos-do%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)
+
+![A screenshot that shows a top toolbar with a custom Back button at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/3342cdf046b51d5b7e22008f4fa36cf8/modal-sheet-watchos-do-not-1%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+![A screenshot that shows a top toolbar with a button with the words Page title at the top of the screen on Apple Watch.](https://docs-assets.developer.apple.com/published/7e655a4130904ed5def637dde60325f9/modal-sheet-watchos-do-not-2%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/sheets#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/sheets#Related)
+
+[Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+
+[Action sheets](https://developer.apple.com/design/human-interface-guidelines/action-sheets)
+
+[Popovers](https://developer.apple.com/design/human-interface-guidelines/popovers)
+
+[Panels](https://developer.apple.com/design/human-interface-guidelines/panels)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/sheets#Developer-documentation)
+
+[`sheet(item:onDismiss:content:)`](https://developer.apple.com/documentation/SwiftUI/View/sheet\(item:onDismiss:content:\)) — SwiftUI
+
+[`UISheetPresentationController`](https://developer.apple.com/documentation/UIKit/UISheetPresentationController) — UIKit
+
+[`presentAsSheet(_:)`](https://developer.apple.com/documentation/AppKit/NSViewController/presentAsSheet\(_:\)) — AppKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/sheets#Change-log)
+
+Date| Changes  
+---|---  
+March 29, 2024| Added guidance to use form or page sheet styles in iPadOS apps.  
+December 5, 2023| Recommended using a split view to offer supplementary items in a visionOS app.  
+June 21, 2023| Updated to include guidance for visionOS.  
+June 5, 2023| Updated guidance for using sheets in watchOS.  
+  

package/skills/hig-components-layout/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: hig-components-layout
+version: 1.0.0
+description: ">"
+  Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user
+  asks about "sidebar", "split view", "tab bar", "tab view", "scroll view", "window design", "panel",
+  "list view", "table view", "column view", "outline view", "navigation structure", "app layout",
+  "boxes", "ornaments", or organizing content hierarchically in Apple apps.
+  Also use when the user says "how should I organize my app", "what navigation pattern should I use",
+  "my layout breaks on iPad", "how do I build a sidebar", "should I use tabs or a sidebar",
+  or "my app doesn't adapt to different screen sizes".
+  Cross-references: hig-foundations for layout/spacing principles, hig-platforms for platform-specific
+  navigation, hig-patterns for multitasking and full-screen, hig-components-content for content display.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Layout and Navigation Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Organize hierarchically.** Structure information from broad categories to specific details. Sidebars for top-level sections, lists for browsable items, detail views for individual content.
+
+2. **Use standard navigation patterns.** Tab bars for flat navigation between peer sections (iPhone). Sidebars for deep hierarchical navigation (iPad, Mac). Match the pattern to the information architecture and platform.
+
+3. **Adapt to screen size.** Three-column on iPad collapses to single-column on iPhone. Use size classes and adaptive APIs (NavigationSplitView) for automatic adaptation.
+
+4. **Support multitasking on iPad.** Respond gracefully to Split View, Slide Over, and Stage Manager. Test at every split ratio and size class transition.
+
+5. **Maintain spatial consistency on visionOS.** Windows, volumes, and ornaments in shared space. Position predictably. Use ornaments for toolbars and controls without occluding content.
+
+6. **Use scroll views for overflow content.** Enable paging for discrete content units. Support pull-to-refresh where appropriate. Respect safe areas.
+
+7. **Keep navigation predictable.** Users should always know where they are, how they got there, and how to go back. Use back buttons, breadcrumbs, and clear section titles.
+
+8. **Prefer system components.** UINavigationController, UISplitViewController, NavigationSplitView, and TabView provide built-in adaptivity, accessibility, and state restoration.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [sidebars.md](references/sidebars.md) | Sidebars | Source lists, selection state, collapsible sections, iPad/Mac patterns |
+| [column-views.md](references/column-views.md) | Column Views | Finder-style browsing, progressive disclosure through columns |
+| [outline-views.md](references/outline-views.md) | Outline Views | Expandable hierarchies, disclosure triangles, tree structures |
+| [split-views.md](references/split-views.md) | Split Views | Two/three column layouts, NavigationSplitView, adaptive collapse |
+| [tab-views.md](references/tab-views.md) | Tab Views | Segmented tabs, page-style tabs, macOS tab grouping |
+| [tab-bars.md](references/tab-bars.md) | Tab Bars | Bottom tab bars (iOS), badge counts, max tab count |
+| [scroll-views.md](references/scroll-views.md) | Scroll Views | Paging, scroll indicators, content insets, pull-to-refresh |
+| [windows.md](references/windows.md) | Windows | macOS/visionOS window management, sizing, full-screen, restoration |
+| [panels.md](references/panels.md) | Panels | Inspector panels, utility panels, floating panels, macOS conventions |
+| [lists-and-tables.md](references/lists-and-tables.md) | Lists and Tables | Plain/grouped/inset-grouped styles, swipe actions, section headers |
+| [boxes.md](references/boxes.md) | Boxes | Content grouping containers, labeled boxes, macOS grouping |
+| [ornaments.md](references/ornaments.md) | Ornaments | visionOS toolbar attachments, positioning, visibility |
+
+## Navigation Pattern Selection
+
+| App Structure | Recommended Pattern | Platform Adaptation |
+|---|---|---|
+| 3-5 peer top-level sections | Tab Bar | iPhone: bottom tab bar. iPad: sidebar (`.sidebarAdaptable`, iPadOS 18+). Mac: sidebar or toolbar tabs |
+| Deep hierarchical content | Sidebar + NavigationSplitView | iPhone: single column stack. iPad: two/three columns. Mac: full multi-column |
+| Deep file/folder tree | Column View | Mac: Finder-style. iPad: adaptable. iPhone: push navigation |
+| Flat list with detail | Split View (two column) | iPhone: push/pop stack. iPad/Mac: primary + detail columns |
+| Document-based with inspectors | Window + Panels | Mac: main window with inspector. iPad: sheet or popover |
+| Spatial app with tools | Window + Ornaments | visionOS: ornaments on window. Other platforms: toolbars |
+
+## Layout Adaptation Checklist
+
+- [ ] **Compact width (iPhone portrait):** Navigation collapses to single stack? Tab bars visible?
+- [ ] **Regular width (iPad landscape, Mac):** Navigation expands to sidebar + detail? Space used well?
+- [ ] **Multitasking (iPad):** Adapts at every split ratio? Works in Slide Over?
+- [ ] **Accessibility:** Supports Dynamic Type at all sizes? VoiceOver order logical?
+- [ ] **Orientation:** Content reflows between portrait and landscape?
+- [ ] **visionOS:** Windows positioned ergonomically? Ornaments accessible? Depth meaningful?
+
+## Output Format
+
+1. **Recommended navigation pattern** with rationale for the app's information architecture.
+2. **Layout hierarchy** from root container down (e.g., TabView > NavigationSplitView > List > Detail).
+3. **Platform adaptation** across targeted platforms and size classes.
+4. **Size class behavior** at each transition.
+
+## Questions to Ask
+
+1. What is the app's information architecture? (Sections, hierarchy depth, top-level categories?)
+2. How many top-level sections?
+3. Which platforms?
+4. Need multitasking on iPad?
+5. SwiftUI or UIKit?
+
+## Related Skills
+
+- **hig-foundations** -- Layout spacing, margins, safe areas, alignment
+- **hig-platforms** -- Platform-specific navigation conventions
+- **hig-patterns** -- Multitasking, full-screen, and launching patterns
+- **hig-components-content** -- Content displayed within layout containers
+
+---
+
+*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/skills/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/skills/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/skills/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/skills/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/skills/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)
+