@ngxtm/devkit 3.15.0 → 3.17.0

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

@@ -0,0 +1,73 @@
+---
+name: hig-components-search
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for navigation-related components including search fields,
+  page controls, and path controls. Use this skill when the user says "how should
+  search work in my app," "I need a breadcrumb," "how do I paginate content," or
+  asks about search field, search bar, page control, path control, breadcrumb,
+  navigation component, search UX, search suggestions, search scopes, paginated
+  content navigation, or file path hierarchy display. Cross-references:
+  hig-components-menus, hig-components-controls, hig-components-dialogs,
+  hig-patterns.
+risk: unknown
+source: community
+---
+
+# Apple HIG: 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. **Search: discoverable with instant feedback.** Place search fields where users expect them (top of list, toolbar/navigation bar). Show results as the user types.
+
+2. **Page controls: position in a flat page sequence.** For discrete, equally weighted pages (onboarding, photo gallery). Show current page and total count.
+
+3. **Path controls: file hierarchy navigation.** macOS path controls display location within a directory structure and allow jumping to any ancestor.
+
+4. **Search scopes narrow large result sets.** Provide scope buttons so users can filter without complex queries.
+
+5. **Clear empty states for search.** Helpful message suggesting corrections or alternatives, not a blank screen.
+
+6. **Page controls are not for hierarchical navigation.** Flat, linear sequences only. Use navigation controllers, tab bars, or sidebars for hierarchy.
+
+7. **Keep path controls concise.** Show meaningful segments only. Users can click any segment to navigate directly.
+
+8. **Support keyboard for search.** Command-F and system search shortcuts should activate search.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [search-fields.md](references/search-fields.md) | Search fields | Scopes, tokens, instant results, placement |
+| [page-controls.md](references/page-controls.md) | Page controls | Dot indicators, flat page sequences |
+| [path-controls.md](references/path-controls.md) | Path controls | Breadcrumbs, ancestor navigation |
+
+## Output Format
+
+1. **Component recommendation** -- search field, page control, or path control, and why.
+2. **Behavior specification** -- interaction model (search-as-you-type, swipe for pages, click-to-navigate for paths).
+3. **Platform differences** across iOS, iPadOS, macOS, visionOS.
+
+## Questions to Ask
+
+1. What type of content is being searched or navigated?
+2. Which platforms?
+3. How large is the dataset?
+4. Is search the primary interaction?
+
+## Related Skills
+
+- **hig-components-menus** -- Toolbars and menu bars hosting search and navigation controls
+- **hig-components-controls** -- Text fields, pickers, segmented controls in search interfaces
+- **hig-components-dialogs** -- Popovers and sheets for expanded search or filtering
+- **hig-patterns** -- Navigation patterns and information architecture
+- **hig-foundations** -- Typography and layout for navigation components
+
+---
+
+*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-search/references/page-controls.md

@@ -0,0 +1,120 @@
+---
+title: "Page controls | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/page-controls
+
+# Page controls
+
+A page control displays a row of indicator images, each of which represents a page in a flat list.
+
+![A stylized representation of a page control with an indicator denoting the active page. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/a0dcd33d7bfca7feb019c4743b89c7c0/components-page-dots-intro%402x.png)
+
+The scrolling row of indicators helps people navigate the list to find the page they want. Page controls can handle an arbitrary number of pages, making them particularly useful in situations where people can create custom lists.
+
+Page controls appear as a series of small indicator dots by default, representing the available pages. A solid dot denotes the current page. Visually, these dots are always equidistant, and are clipped if there are too many to fit in the window.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/page-controls#Best-practices)
+
+**Use page controls to represent movement between an ordered list of pages.** Page controls don’t represent hierarchical or nonsequential page relationships. For more complex navigation, consider using a sidebar or split view instead.
+
+**Center a page control at the bottom of the view or window.** To ensure people always know where to find a page control, center it horizontally and position it near the bottom of the view.
+
+**Although page controls can handle any number of pages, don’t display too many**. More than about 10 dots are hard to count at a glance. If your app needs to display more than 10 pages as peers, consider using a different arrangement‚ such as a grid, that lets people navigate the content in any order.
+
+## [Customizing indicators](https://developer.apple.com/design/human-interface-guidelines/page-controls#Customizing-indicators)
+
+By default, a page control uses the system-provided dot image for all indicators, but it can also display a unique image to help people identify a specific page. For example, Weather uses the `location.fill` symbol to distinguish the current location’s page.
+
+If it enhances your app or game, you can provide a custom image to use as the default image for all indicators and you can also supply a different image for a specific page. For developer guidance, see [`preferredIndicatorImage`](https://developer.apple.com/documentation/UIKit/UIPageControl/preferredIndicatorImage) and [`setIndicatorImage(_:forPage:)`](https://developer.apple.com/documentation/UIKit/UIPageControl/setIndicatorImage\(_:forPage:\)).
+
+**Make sure custom indicator images are simple and clear.** Avoid complex shapes, and don’t include negative space, text, or inner lines, because these details can make an icon muddy and indecipherable at very small sizes. Consider using simple [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) as indicators or design your own icons. For guidance, see [Icons](https://developer.apple.com/design/human-interface-guidelines/icons).
+
+**Customize the default indicator image only when it enhances the page control’s overall meaning.** For example, if every page you list contains bookmarks, you might use the `bookmark.fill` symbol as the default indicator image.
+
+**Avoid using more than two different indicator images in a page control.** If your list contains one page with special meaning — like the current-location page in Weather — you can make the page easy to find by giving it a unique indicator image. In contrast, a page control that uses several unique images to mark several important pages is hard to use because people must memorize the meaning of each image. A page control that displays more than two types of indicator images tends to look messy and haphazard, even when each image is clear.
+
+![An illustration that represents the Weather app highlighted to show a page control at the bottom edge of the screen. The page control displays a mix of icons, such as weak sun, cloud, cloud with sun, and cloud with drizzle.](https://docs-assets.developer.apple.com/published/671a959d0a2a6baf234fcc2255b9abdb/page-indicator-customization-incorrect%402x.png)
+
+![An X in a circle to indicate an incorrect example.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)Using several different indicators can make a page control look busy and difficult to use.
+
+![An illustration that represents the Weather app highlighted to show a page control at the bottom edge of the screen. The page control displays the location symbol on the leading side followed by a series of dots.](https://docs-assets.developer.apple.com/published/b797a18ec978a588e29113b3a9f522b7/page-indicator-customization-correct%402x.png)
+
+![A checkmark in a circle to indicate a correct example.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)Using only two different indicators looks well-organized and provides a consistent experience.
+
+**Avoid coloring indicator images.** Custom colors can reduce the contrast that differentiates the current-page indicator and makes the page control visible on the screen. To ensure that your page control is easy to use and looks good in different contexts, let the system automatically color the indicators.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/page-controls#Platform-considerations)
+
+ _Not supported in macOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/page-controls#iOS-iPadOS)
+
+A page control can adjust the appearance of indicators to provide more information about the list. For example, the control highlights the indicator of the current page so people can estimate the page’s relative position in the list. When there are more indicators than fit in the space, the control can shrink indicators at both sides to suggest that more pages are available.
+
+![An illustration of a page control. The page control displays a total of 9 dots. The center 5 dots use the default size; the second and eighth dots are about half the default size and the first and ninth dots are about one quarter the default size. The center dot is filled, indicating the location of the current page in the list.](https://docs-assets.developer.apple.com/published/6413d2970c5a12e6374d83bed419293c/page-controls-many-indicators%402x.png)
+
+People interact with page controls by tapping or scrubbing (to _scrub_ , people touch the control and drag left or right). Tapping on the leading or trailing side of the current-page indicator reveals the next or previous page; in iPadOS, people can also use the pointer to target a specific indicator. Scrubbing opens pages in sequence, and scrubbing past the leading or trailing edge of the control helps people quickly reach the first or last page.
+
+Developer note
+
+In the API, _tapping_ is a _discrete interaction_ , whereas _scrubbing_ is a _continuous interaction_ ; for developer guidance, see [`UIPageControl.InteractionState`](https://developer.apple.com/documentation/UIKit/UIPageControl/InteractionState-swift.enum).
+
+**Avoid animating page transitions during scrubbing.** People can scrub very quickly, and using the scrolling animation for every transition can make your app lag and cause distracting visual flashes. Use the animated scrolling transition only for tapping.
+
+A page control can include a translucent, rounded-rectangle background appearance that provides visual contrast for the indicators. You can choose one of the following background styles:
+
+  * Automatic — Displays the background only when people interact with the control. Use this style when the page control isn’t the primary navigational element in the UI.
+
+  * Prominent — Always displays the background. Use this style only when the control is the primary navigational control in the screen.
+
+  * Minimal — Never displays the background. Use this style when you just want to show the position of the current page in the list and you don’t need to provide visual feedback during scrubbing.
+
+
+
+
+For developer guidance, see [`backgroundStyle`](https://developer.apple.com/documentation/UIKit/UIPageControl/backgroundStyle-swift.property).
+
+**Avoid supporting the scrubber when you use the minimal background style.** The minimal style doesn’t provide visual feedback during scrubbing. If you want to let people scrub a list of pages in your app, use the automatic or prominent background styles.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/page-controls#tvOS)
+
+**Use page controls on collections of full-screen pages.** A page control is designed to operate in a full-screen environment where multiple content-rich pages are peers in the page hierarchy. Inclusion of additional controls makes it difficult to maintain focus while moving between pages.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/page-controls#visionOS)
+
+In visionOS, page controls represent available pages and indicate the current page, but people don’t interact with them.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/page-controls#watchOS)
+
+In watchOS, page controls can be displayed at the bottom of the screen for horizontal pagination, or next to the Digital Crown when presenting a vertical [tab view](https://developer.apple.com/design/human-interface-guidelines/components/layout-and-organization/tab-views). When using vertical tab views, the page indicator shows people where they are in the navigation, both within the current page and within the set of pages. The page control transitions between scrolling through a page’s content and scrolling to other pages.
+
+![An illustration representing a screen that includes a vertical tab view on Apple Watch. A page control next to the Digital Crown shows that the fourth tab is currently selected.](https://docs-assets.developer.apple.com/published/d8ac19e2578c57035e74fe697a15d573/page-controls-watch-vertical%402x.png)
+
+Vertical page control
+
+![An illustration representing a screen that includes a horizontal tab view on Apple Watch. A page control at the bottom shows that the second tab is currently selected.](https://docs-assets.developer.apple.com/published/0f915ec7b0e8755a2d60845617746f71/page-controls-watch-horizontal%402x.png)
+
+Horizontal page control
+
+**Use vertical pagination to separate multiple views into distinct, purposeful pages.** Give each page a clear purpose, and let people scroll through the pages using the Digital Crown. In watchOS, this design is more effective than horizontal pagination or many levels of hierarchical navigation.
+
+**Consider limiting the content of an individual page to a single screen height.** Embracing this constraint encourages each page to serve a clear and distinct purpose and results in a more glanceable design. Use variable-height pages judiciously and, if possible, only place them after fixed-height pages in your app design.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/page-controls#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/page-controls#Related)
+
+[Scroll views](https://developer.apple.com/design/human-interface-guidelines/scroll-views)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/page-controls#Developer-documentation)
+
+[`PageTabViewStyle`](https://developer.apple.com/documentation/SwiftUI/PageTabViewStyle) — SwiftUI
+
+[`UIPageControl`](https://developer.apple.com/documentation/UIKit/UIPageControl) — UIKit
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/page-controls#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+June 5, 2023| Updated guidance for using page controls in watchOS.  
+  

package/skills/hig-components-search/references/path-controls.md

@@ -0,0 +1,40 @@
+---
+title: "Path controls | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/path-controls
+
+# Path controls
+
+A path control shows the file system path of a selected file or folder.
+
+![A stylized representation of a path control for a HIG Design document showing its root disk, parent folder, and selected item. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/1266fc8267f96dc76fb9247aa5f08618/components-path-control-intro%402x.png)
+
+For example, choosing View > Show Path Bar in the Finder displays a path bar at the bottom of the window. It shows the path of the selected item, or the path of the window’s folder if nothing is selected.
+
+There are two styles of path control.
+
+![A screenshot of a Finder path bar that displays a hierarchy of four locations.](https://docs-assets.developer.apple.com/published/c7347a80a423da7a3886208113258675/path-controls-standard%402x.png)
+
+**Standard.** A linear list that includes the root disk, parent folders, and selected item. Each item appears with an icon and a name. If the list is too long to fit within the control, it hides names between the first and last items. If you make the control editable, people can drag an item onto the control to select the item and display its path in the control.
+
+![A screenshot of a path control showing a folder icon and a pop-up control.](https://docs-assets.developer.apple.com/published/6768a6d2292f05923976b90cd80c931d/path-controls-popup%402x.png)
+
+**Pop up.** A control similar to a [pop-up button](https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons) that shows the icon and name of the selected item. People can click the item to open a menu containing the root disk, parent folders, and selected item. If you make the control editable, the menu contains an additional Choose command that people can use to select an item and display it in the control. They can also drag an item onto the control to select it and display its path.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/path-controls#Best-practices)
+
+**Use a path control in the window body, not the window frame.** Path controls aren’t intended for use in toolbars or status bars. Note that the path control in the Finder appears at the bottom of the window body, not in the status bar.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/path-controls#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/path-controls#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/path-controls#Related)
+
+[File management](https://developer.apple.com/design/human-interface-guidelines/file-management)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/path-controls#Developer-documentation)
+
+[`NSPathControl`](https://developer.apple.com/documentation/AppKit/NSPathControl) — AppKit
+

package/skills/hig-components-search/references/search-fields.md

@@ -0,0 +1,189 @@
+---
+title: "Search fields | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/search-fields
+
+# Search fields
+
+A search field lets people search a collection of content for specific terms they enter.
+
+![A stylized representation of a search field containing placeholder text and a dictation icon. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/73f9e564b79cbe48e29ae2a9f7b83682/components-search-field-intro%402x.png)
+
+A search field is an editable text field that displays a Search icon, a Clear button, and placeholder text where people can enter what they are searching for. Search fields can use a [scope control](https://developer.apple.com/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens) as well as [tokens](https://developer.apple.com/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens) to help filter and refine the scope of their search. Across each platform, there are different patterns for accessing search based on the goals and design of your app.
+
+For developer guidance, see [Adding a search interface to your app](https://developer.apple.com/documentation/SwiftUI/Adding-a-search-interface-to-your-app); for guidance related to systemwide search, see [Searching](https://developer.apple.com/design/human-interface-guidelines/searching).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/search-fields#Best-practices)
+
+**Display placeholder text that describes the type of information people can search for.** For example, the Apple TV app includes the placeholder text _Shows, Movies, and More_. Avoid using a term like _Search_ for placeholder text because it doesn’t provide any helpful information.
+
+**If possible, start search immediately when a person types.** Searching while someone types makes the search experience feel more responsive because it provides results that are continuously refined as the text becomes more specific.
+
+**Consider showing suggested search terms before search begins, or as a person types.** This can help someone search faster by suggesting common searches, even when the search itself doesn’t begin immediately.
+
+**Simplify search results.** Provide the most relevant search results first to minimize the need for someone to scroll to find what they’re looking for. In addition to prioritizing the most likely results, consider categorizing them to help people find what they want.
+
+**Consider letting people filter search results.** For example, you can include a scope control in the search results content area to help people quickly and easily filter search results.
+
+## [Scope controls and tokens](https://developer.apple.com/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens)
+
+Scope controls and tokens are components you can use to let someone narrow the parameters of a search either before or after they make it.
+
+  * A _scope control_ acts like a [segmented control](https://developer.apple.com/design/human-interface-guidelines/segmented-controls) for choosing a category for the search.
+
+  * A _token_ is a visual representation of a search term that someone can select and edit, and acts as a filter for any additional terms in the search.
+
+
+
+
+![A diagram of the Mail app on iPhone with the search field open above the keyboard and the word Design entered in the field. Callouts indicate a scope control at the top of the screen to switch between searching all mailboxes and the current mailbox, and a list of tokens in a Suggestions area beneath the control that represent different filters for the search.](https://docs-assets.developer.apple.com/published/c39602d60041fae736e46f91641d8373/search-fields-scope-control-tokens%402x.png)
+
+**Use a scope control to filter among clearly defined search categories.** A scope control can help someone move from a broader scope to a narrower one. For example, in Mail on iPhone, a scope control helps people move from searching their entire mailbox to just the specific mailbox they’re viewing. For developer guidance, see [Scoping a search operation](https://developer.apple.com/documentation/SwiftUI/Scoping-a-search-operation).
+
+**Default to a broader scope and let people refine it as they need.** A broader scope provides context for the full set of available results, which helps guide people in a useful direction when they choose to narrow the scope.
+
+**Use tokens to filter by common search terms or items.** When you define a token, the term it represents gains a visual treatment that encapsulates it, indicating that people can select and edit it as a single item. Tokens can clarify a search term, like filtering by a specific contact in Mail, or focus a search to a specific set of attributes, like filtering by photos in Messages. For the related macOS component, see [Token fields](https://developer.apple.com/design/human-interface-guidelines/token-fields).
+
+**Consider pairing tokens with search suggestions.** People may not know which tokens are available, so pairing them with search suggestions can help people learn how to use them.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/search-fields#Platform-considerations)
+
+ _No additional considerations for visionOS_.
+
+### [iOS](https://developer.apple.com/design/human-interface-guidelines/search-fields#iOS)
+
+There are three main places you can position the entry point for search:
+
+  * In a tab bar at the bottom of the screen
+
+  * In a toolbar at the bottom or top of the screen
+
+  * Directly inline with content
+
+
+
+
+Where search makes the most sense depends on the layout, content, and navigation of your app.
+
+#### [Search in a tab bar](https://developer.apple.com/design/human-interface-guidelines/search-fields#Search-in-a-tab-bar)
+
+You can place search as a visually distinct tab on the trailing side of a tab bar, which keeps search visible and always available as people switch between the sections of your app.
+
+![An illustration of a tab bar at the bottom of an iPhone screen. A tab for search appears on the trailing edge in a visually distinct group.](https://docs-assets.developer.apple.com/published/ca6977596a62743265fdd2132616a4c8/search-fields-search-as-tab%402x.png)
+
+When someone navigates to the search tab, the search field that appears can start as _focused_ or _unfocused_.
+
+![An illustration of an iPhone screen with search in a tab bar at the bottom of the screen. The tab bar is hidden by the keyboard and the search field is open above the keyboard, ready for text entry.](https://docs-assets.developer.apple.com/published/cbd1eb280ecd0f8f71aab784a2bcd042/search-fields-tab-focused%402x.png)
+
+Focused
+
+![An illustration of an iPhone screen with search in a tab bar at the bottom of the screen. The search tab is expanded into a field that hides the tabs to its leading side. A single remaining tab on the leading edge of the screen indicates that it's possible to navigate away, and the space above the tab bar is empty and available for other content.](https://docs-assets.developer.apple.com/published/196b81213f5131b324f952180a4e9c46/search-fields-tab-unfocused%402x.png)
+
+Unfocused
+
+**Start with the search field focused to help people quickly find what they need.** When the search field starts focused, the keyboard immediately appears with the search field above it, ready to begin the search. This provides a more transient experience that brings people directly back to their previous tab after they exit search, and is ideal when you want search to resolve quickly and seamlessly.
+
+**Start with the search field unfocused to promote discovery and exploration.** When the search field starts unfocused, the search tab expands into an unselected field at the bottom of the screen. This provides space on the rest of the screen for additional discovery or navigation before someone taps the field to begin the search. This is great for an app with a large collection of content to showcase, like Music or TV.
+
+#### [Search in a toolbar](https://developer.apple.com/design/human-interface-guidelines/search-fields#Search-in-a-toolbar)
+
+As an alternative to search in a tab bar, you can also place search in a toolbar either at the bottom or top of the screen.
+
+  * You can include search in a bottom toolbar either as an expanded field or as a toolbar button, depending on how much space is available and how important search is to your app. When someone taps it, it animates into a search field above the keyboard so they can begin typing.
+
+  * You can include search in a top toolbar, also called a navigation bar, where it appears as a toolbar button. When someone taps it, it animates into a search field that appears either above the keyboard or inline at the top if there isn’t space at the bottom.
+
+
+
+
+![An illustration of an iPhone screen with search in a bottom toolbar. The search field is positioned in an isolated group between a Filter button on the leading edge and a Compose button on the trailing edge.](https://docs-assets.developer.apple.com/published/face9eed2f9c99f2c12ca3a400919e03/search-fields-ios-toolbar-with-items%402x.png)
+
+Search in a bottom toolbar
+
+![An illustration of an iPhone screen with search in a top toolbar. A Back button appears on the leading edge, and an Add button appears on the trailing edge. An button group with Search and More appears next to the Add button.](https://docs-assets.developer.apple.com/published/ca4d0118cd29bd05bd2fd114163a1f64/search-fields-ios-navigation-bar-item%402x.png)
+
+Search in a top toolbar
+
+**Place search at the bottom if there’s room.** You can either add a search field to an existing toolbar, or as a new toolbar where search is the only item. Search at the bottom is useful in any situation where search is a priority, since it keeps the search experience easy to reach. Examples of apps with search at the bottom in various toolbar layouts include Settings, where it’s the only item, and Mail and Notes, where it fits alongside other important controls.
+
+**Place search at the top when itʼs important to defer to content at the bottom of the screen, or thereʼs no bottom toolbar.** Use search at the top in cases where covering the content might interfere with a primary function of the app. The Wallet app, for example, includes event passes in a stack at the bottom of the screen for easy access and viewing at a glance.
+
+#### [Search as an inline field](https://developer.apple.com/design/human-interface-guidelines/search-fields#Search-as-an-inline-field)
+
+In some cases you might want your app to include a search field inline with content.
+
+**Place search as an inline field when its position alongside the content it searches strengthens that relationship.** When you need to filter or search within a single view, it can be helpful to have search appear directly next to content to illustrate that the search applies to it, rather than globally. For example, although the main search in the Music app is in the tab bar, people can navigate to their library and use an inline search field to filter their songs and albums.
+
+**Prefer placing search at the bottom.** Generally, even for search that applies to a subset of your app’s content, it’s better to locate search where people can reach it easily. The Settings app, for example, places search at the bottom both for its top-level search and for search in the section for individual apps. If there isn’t space at the bottom (because it’s occupied by a tab bar or other important UI, for example), it’s okay to place search inline at the top.
+
+**When at the top, position an inline search field above the list it searches, and pin it to the top toolbar when scrolling.** This helps keep it distinct from search that appears in other locations.
+
+### [iPadOS, macOS](https://developer.apple.com/design/human-interface-guidelines/search-fields#iPadOS-macOS)
+
+The placement and behavior of the search field in iPadOS and macOS is similar; on both platforms, clearing the field exits search and dismisses the keyboard if present. If your app is available on both iPad and Mac, try to keep the search experience as consistent as possible across both platforms.
+
+![An illustration of an iPad screen with a search field on the trailing edge of the top toolbar. The search field has the word Design entered into the field, and three search suggestions appear in a list beneath the field. The toolbar also includes an Inspector button, a group with New Folder and Favorite buttons, and a Share button next to the search field.](https://docs-assets.developer.apple.com/published/368ba21a44b4c65a4e53d3d2197d061b/search-fields-toolbar-search-ipad%402x.png)iPadOS
+
+![An illustration of a Mac screen with a search field on the trailing edge of the toolbar. The search field has the word Design entered into the field, and three search suggestions appear in a list beneath the field. The toolbar also includes an Inspector button, a group with New Folder and Favorite buttons, and a Share button next to the search field.](https://docs-assets.developer.apple.com/published/eb1970b09f7b35b39757201a31289bc3/search-fields-toolbar-search-mac%402x.png)macOS
+
+**Put a search field at the trailing side of the toolbar for many common uses.** Many apps benefit from the familiar pattern of search in the toolbar, particularly apps with split views or apps that navigate between multiple sources, like Mail, Notes, and Voice Memos. The persistent availability of search at the side of the toolbar gives it a global presence within your app, so it’s generally appropriate to start with a global scope for the initial search.
+
+**Include search at the top of the sidebar when filtering content or navigation there.** Apps such as Settings take advantage of search to quickly filter the sidebar and expose sections that may be multiple levels deep, providing a simple way for people to search, preview, and navigate to the section or setting they’re looking for.
+
+![An illustration of an iPad screen with a search field at the top of the sidebar on the leading edge of the screen.](https://docs-assets.developer.apple.com/published/8aed61a23fe2a9885d1a1d1da15a4b09/search-fields-ipad-search-in-sidebar%402x.png)
+
+**Include search as an item in the sidebar or tab bar when you want an area dedicated to discovery.** If your search is paired with rich suggestions, categories, or content that needs more space, it can be helpful to have a dedicated area for it. This is particularly true for apps where browsing and search go hand in hand, like Music and TV, where it provides a unified location to highlight suggested content, categories, and recent searches. A dedicated area also ensures search is always available as people navigate and switch sections of your app.
+
+![An illustration of an iPad screen with a tab bar at the top edge. The trailing side of the tab bar includes a Search tab with a distinct background color to differentiate it from other tab areas.](https://docs-assets.developer.apple.com/published/a2ab9bc29018fc1bbc604a91dfc905c7/search-fields-ipad-search-in-tab-bar%402x.png)
+
+**In a search field in a dedicated area, consider immediately focusing the field when a person navigates to the section to help people search faster and locate the field itself more easily.** An exception to this is on iPad when only a virtual keyboard is available, in which case it’s better to leave the field unfocused to prevent the keyboard from unexpectedly covering the view.
+
+**Account for window resizing with the placement of the search field.** On iPad, the search field fluidly resizes with the app window like it does on Mac. However, for compact views on iPad, itʼs important to ensure that search is available where it’s most contextually useful. For example, Notes and Mail place search above the column for the content list when they resize down to a compact view.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/search-fields#tvOS)
+
+A search screen is a specialized keyboard screen that helps people enter search text, displaying search results beneath the keyboard in a fully customizable view. For developer guidance, see [`UISearchController`](https://developer.apple.com/documentation/UIKit/UISearchController).
+
+![An illustration of a search screen in tvOS. The screen includes a field with a keyboard input area at the top, a scope control, and a grid of top results at the bottom.](https://docs-assets.developer.apple.com/published/590a4ef7b02ccd9758f0e52e5c261574/search-fields-tvos-search%402x.png)
+
+**Provide suggestions to make searching easier.** People typically don’t want to do a lot of typing in tvOS. To improve the search experience, provide popular and context-specific search suggestions, including recent searches when available. For developer guidance, see [Using suggested searches with a search controller](https://developer.apple.com/documentation/UIKit/using-suggested-searches-with-a-search-controller).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/search-fields#watchOS)
+
+When someone taps the search field, the system displays a text-input control that covers the entire screen. The app only returns to the search field after they tap the Cancel or Search button.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/search-fields#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/search-fields#Related)
+
+[Searching](https://developer.apple.com/design/human-interface-guidelines/searching)
+
+[Token fields](https://developer.apple.com/design/human-interface-guidelines/token-fields)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/search-fields#Developer-documentation)
+
+[Adding a search interface to your app](https://developer.apple.com/documentation/SwiftUI/Adding-a-search-interface-to-your-app) — SwiftUI
+
+[`searchable(text:placement:prompt:)`](https://developer.apple.com/documentation/SwiftUI/View/searchable\(text:placement:prompt:\)) — SwiftUI
+
+[`UISearchBar`](https://developer.apple.com/documentation/UIKit/UISearchBar) — UIKit
+
+[`UISearchTextField`](https://developer.apple.com/documentation/UIKit/UISearchTextField) — UIKit
+
+[`NSSearchField`](https://developer.apple.com/documentation/AppKit/NSSearchField) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/search-fields#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/1AAA030E-2ECA-47D8-AE09-6D7B72A840F6/10044_wide_250x141_1x.jpg) Get to know the new design system ](https://developer.apple.com/videos/play/wwdc2025/356)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/BE8FF113-0FE1-40FC-86BF-FE95BE2FF7A5/5027_wide_250x141_1x.jpg) Discoverable design ](https://developer.apple.com/videos/play/wwdc2021/10126)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/D45C244B-2038-4692-99A0-6131ED5FD984/5084_wide_250x141_1x.jpg) Craft search experiences in SwiftUI ](https://developer.apple.com/videos/play/wwdc2021/10176)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/search-fields#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Updated guidance for search placement in iOS, consolidated iPadOS and macOS platform considerations, and added guidance for tokens.  
+September 12, 2023| Combined guidance common to all platforms.  
+June 5, 2023| Added guidance for using search fields in watchOS.  
+  

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

@@ -0,0 +1,91 @@
+---
+name: hig-components-status
+version: 1.0.0
+description: ">"
+  Apple HIG guidance for status and progress UI components including progress indicators,
+  status bars, and activity rings. Use this skill when asked about: "progress indicator",
+  "progress bar", "loading spinner", "status bar", "activity ring", "progress display",
+  determinate vs indeterminate progress, loading states, or fitness tracking rings.
+  Also use when the user says "how do I show loading state," "should I use a spinner
+  or progress bar," "what goes in the status bar," or asks about activity indicators.
+  Cross-references: hig-components-system for widgets and complications,
+  hig-inputs for gesture-driven progress controls, hig-technologies for HealthKit
+  and activity ring data integration.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Status Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+### Progress Indicators
+
+1. **Show progress for operations longer than a second or two.**
+
+2. **Determinate when duration/percentage is known.** A filling progress bar gives users a clear sense of remaining work. Use for downloads, uploads, or any measurable process.
+
+3. **Indeterminate when duration is unknown.** A spinner communicates work is happening without promising a timeframe. Use for unpredictable network requests.
+
+4. **Prefer progress bars over spinners.** Determinate progress feels faster and more trustworthy.
+
+5. **Place indicators where content will appear.** Inline progress near the content area, not modal or distant.
+
+6. **Don't stack multiple indicators.** Aggregate simultaneous operations into one representation or show the most relevant.
+
+### Status Bars
+
+7. **Don't hide the status bar without good reason.** Reserve hiding for immersive experiences (full-screen media, games, AR).
+
+8. **Match status bar style to your content.** Light or dark for adequate contrast.
+
+9. **Respect safe areas.** No interactive content behind the status bar.
+
+10. **Restore promptly** when exiting immersive contexts.
+
+### Activity Rings
+
+11. **Activity rings are for Move, Exercise, and Stand goals.** Don't repurpose the ring metaphor for unrelated data.
+
+12. **Respect ring color conventions.** Red (Move), green (Exercise), blue (Stand) are strongly associated with Apple Fitness.
+
+13. **Use HealthKit APIs** for activity data rather than manual tracking.
+
+14. **Celebrate completions** with animation and haptics when rings close.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [progress-indicators.md](references/progress-indicators.md) | Progress bars and spinners | Determinate, indeterminate, inline placement, duration |
+| [status-bars.md](references/status-bars.md) | iOS/iPadOS status bar | System info, visibility, style, safe areas |
+| [activity-rings.md](references/activity-rings.md) | watchOS activity rings | Move/Exercise/Stand, HealthKit, fitness tracking, color |
+
+## Output Format
+
+1. **Indicator type recommendation** with rationale (determinate vs indeterminate).
+2. **Timing and animation guidance** -- duration thresholds, animation style, transitions.
+3. **Accessibility** -- VoiceOver progress announcements, live region updates.
+4. **Platform-specific behavior** across targeted platforms.
+
+## Questions to Ask
+
+1. Is the duration known or unknown?
+2. Which platforms?
+3. How long does the operation typically take?
+4. System-level or in-app indicator?
+
+## Related Skills
+
+- **hig-components-system** -- Widgets and complications displaying progress or status
+- **hig-inputs** -- Gestures triggering progress states (pull-to-refresh)
+- **hig-technologies** -- HealthKit for activity ring data; VoiceOver for progress announcements
+
+---
+
+*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.