@ngxtm/devkit 3.14.0 → 3.16.0

package/skills/hig-components-system/references/notifications.md

@@ -0,0 +1,153 @@
+---
+title: "Notifications | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/notifications
+
+# Notifications
+
+A notification gives people timely, high-value information they can understand at a glance.
+
+![A stylized representation of a notification mockup. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/49d8e391f869407a8b755b57ee180c83/components-notification-intro%402x.png)
+
+Before you can send any notifications to people, you have to get their consent (for developer guidance, see [Asking permission to use notifications](https://developer.apple.com/documentation/UserNotifications/asking-permission-to-use-notifications)). After agreeing, people generally use settings to specify the styles of notification they want to receive, and to specify delivery times for notifications that have different levels of urgency. To learn more about the ways people can customize the notification experience, see [Managing notifications](https://developer.apple.com/design/human-interface-guidelines/managing-notifications).
+
+## [Anatomy](https://developer.apple.com/design/human-interface-guidelines/notifications#Anatomy)
+
+Depending on the platform, a notification can use various styles, such as:
+
+  * A banner or view on a Lock Screen, Home Screen, Home View, or desktop
+
+  * A badge on an app icon
+
+  * An item in Notification Center
+
+
+
+
+In addition, a notification related to direct communication — like a phone call or message — can provide an interface that’s distinct from noncommunication notifications, featuring prominent contact images (or _avatars_) and group names instead of the app icon.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/notifications#Best-practices)
+
+**Provide concise, informative notifications.** People turn on notifications to get quick updates, so you want to provide valuable information succinctly.
+
+**Avoid sending multiple notifications for the same thing, even if someone hasn’t responded.** People attend to notifications at their convenience. If you send multiple notifications for the same thing, you fill up Notification Center, and people may turn off all notifications from your app.
+
+**Avoid sending a notification that tells people to perform specific tasks within your app.** If it makes sense to offer simple tasks that people can perform without opening your app, you can provide [notification actions](https://developer.apple.com/design/human-interface-guidelines/notifications#Notification-actions). Otherwise, avoid telling people what to do because it’s hard for people to remember such instructions after they dismiss the notification.
+
+**Use an alert — not a notification — to display an error message.** People are familiar with both alerts and notifications, so you don’t want to cause confusion by using the wrong component. For guidance, see [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts).
+
+**Handle notifications gracefully when your app is in the foreground.** Your app’s notifications don’t appear when your app is in the front, but your app still receives the information. In this scenario, present the information in a way that’s discoverable but not distracting or invasive, such as incrementing a badge or subtly inserting new data into the current view. For example, when a new message arrives in a mailbox that people are currently viewing, Mail simply adds it to the list of unread messages because sending a notification about it would be unnecessary and distracting.
+
+**Avoid including sensitive, personal, or confidential information in a notification.** You can’t predict what people will be doing when they receive a notification, so it’s essential to avoid including private information that could be visible to others.
+
+## [Content](https://developer.apple.com/design/human-interface-guidelines/notifications#Content)
+
+When a notification includes a title, the system displays it at the top where it’s most visible. In a notification related to direct communication, the system automatically displays the sender’s name in the title area; in a noncommunication notification, the system displays your app name if you don’t provide a title.
+
+**Create a short title if it provides context for the notification content.** Prefer brief titles that people can read at a glance, especially on Apple Watch, where space is limited. When possible, take advantage of the prominent notification title area to provide useful information, like a headline, event name, or email subject. If you can only provide a generic title for a noncommunication notification — like New Document — it can be better to let the system display your app name instead. Use title-style [capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64) and no ending punctuation.
+
+**Write succinct, easy-to-read notification content.** Use complete sentences, sentence case, and proper punctuation, and don’t truncate your message — the system does this automatically when necessary.
+
+**Provide generically descriptive text to display when notification previews aren’t available.** In Settings, people can choose to hide notification previews for all apps. In this situation, the system shows only your app icon and the default title _Notification_. To give people sufficient context to know whether they want to view the full notification, write body text that succinctly describes the notification content without revealing too many details, like “Friend request,” “New comment,” “Reminder,” or “Shipment” (for developer guidance, see [`hiddenPreviewsBodyPlaceholder`](https://developer.apple.com/documentation/UserNotifications/UNNotificationCategory/hiddenPreviewsBodyPlaceholder)). Use sentence-style [capitalization](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web#apdca93e113f1d64) for this text.
+
+**Avoid including your app name or icon.** The system automatically displays a large version of your app icon at the leading edge of each notification; in a communication notification, the system displays the sender’s contact image badged with a small version of your icon.
+
+**Consider providing a sound to supplement your notifications.** Sound can be a great way to distinguish your app’s notifications and get someone’s attention when they’re not looking at the device. You can create a custom sound that coordinates with the style of your app or use a system-provided alert sound. If you use a custom sound, make sure it’s short, distinctive, and professionally produced. A notification sound can enhance the user experience, but don’t rely on it to communicate important information, because people may not hear it. Although people might also want a vibration to accompany alert sounds, you can’t provide such a vibration programmatically. For developer guidance, see [`UNNotificationSound`](https://developer.apple.com/documentation/UserNotifications/UNNotificationSound).
+
+## [Notification actions](https://developer.apple.com/design/human-interface-guidelines/notifications#Notification-actions)
+
+A notification can present a customizable detail view that contains up to four buttons people use to perform actions without opening your app. For example, a Calendar event notification provides a Snooze button that postpones the event’s alarm for a few minutes. For developer guidance, see [Handling notifications and notification-related actions](https://developer.apple.com/documentation/UserNotifications/handling-notifications-and-notification-related-actions).
+
+**Provide beneficial actions that make sense in the context of your notification.** Prefer actions that let people perform common, time-saving tasks that eliminate the need to open your app. For each button, use a short, title-case term or phrase that clearly describes the result of the action. Don’t include your app name or any extraneous information in the button label, keep the text brief to avoid truncation, and take localization into account as you write it.
+
+**Avoid providing an action that merely opens your app.** When people tap a notification or its preview, they expect your app to display related content, so presenting an action button that does the same thing clutters the detail view and can be confusing.
+
+**Prefer nondestructive actions.** If you must provide a destructive action, make sure people have enough context to avoid unintended consequences. The system gives a distinct appearance to the actions you identify as destructive.
+
+**Provide a simple, recognizable interface icon for each notification action.** An interface icon reinforces an action’s meaning, helping people instantly understand what it does. The system displays your interface icon on the trailing side of the action title. When you use [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols), you can choose an existing symbol that represents your command or edit a related symbol to create a custom icon.
+
+## [Badging](https://developer.apple.com/design/human-interface-guidelines/notifications#Badging)
+
+A badge is a small, filled oval containing a number that can appear on an app icon to indicate the number of unread notifications that are available. After people address unread notifications, the badge disappears from the app icon, reappearing when new notifications arrive. People can choose whether to allow an app to display badges in their notification settings.
+
+**Use a badge only to show people how many unread notifications they have.** Don’t use a badge to convey numeric information that isn’t related to notifications, such as weather-related data, dates and times, stock prices, or game scores.
+
+**Make sure badging isn’t the only method you use to communicate essential information.** People can turn off badging for your app, so if you rely on it to show people when there’s important information, people can miss the message. Always make sure that you make important information easy for people to find as soon as they open your app.
+
+**Keep badges up to date.** Update your app’s badge as soon as people open the corresponding notifications. You don’t want people to think there are new notifications available, only to find that they’ve already viewed them all. Note that reducing a badge’s count to zero removes all related notifications from Notification Center.
+
+**Avoid creating a custom image or component that mimics the appearance or behavior of a badge.** People can turn off notification badges if they choose, and will become frustrated if they have done so and then see what appears to be a badge.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/notifications#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS._
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/notifications#watchOS)
+
+On Apple Watch, notifications occur in two stages: _short look_ and _long look_. People can also view notifications in Notification Center. On supported devices, people can double-tap to respond to notifications.
+
+You can help people have a great notification experience by designing app-specific assets and actions that are relevant on Apple Watch. If your watchOS app has an iPhone companion that supports notifications, watchOS can automatically provide default short-look and long-look interfaces if necessary.
+
+#### [Short looks](https://developer.apple.com/design/human-interface-guidelines/notifications#Short-looks)
+
+A short look appears when the wearer’s wrist is raised and disappears when it’s lowered.
+
+![An illustration that represents a short look notification from a generic app. It includes a large primary image in the center, a title, and a short preview of the notification content.](https://docs-assets.developer.apple.com/published/609f4ae816d78b5c87a340416f4874a9/notifications-short-looks%402x.png)
+
+**Avoid using a short look as the only way to communicate important information.** A short look appears only briefly, giving people just enough time to see what the notification is about and which app sent it. If your notification information is critical, make sure you deliver it in other ways, too.
+
+**Keep privacy in mind.** Short looks are intended to be discreet, so it’s important to provide only basic information. Avoid including potentially sensitive information in the notification’s title.
+
+#### [Long looks](https://developer.apple.com/design/human-interface-guidelines/notifications#Long-looks)
+
+Long looks provide more detail about a notification. If necessary, people can swipe vertically or use the Digital Crown to scroll a long look. After viewing a long look, people can dismiss it by tapping it or simply by lowering their wrist.
+
+![An illustration that represents a long look notification from a generic app. It includes a small primary image in the upper left corner, badging a platter with the notification title and content. Beneath the notification are two full width action buttons, the second of which extends off the screen to indicate that the view is scrollable.](https://docs-assets.developer.apple.com/published/a48f434c960e0f14429018803ee4b180/notifications-long-looks%402x.png)
+
+A custom long-look interface can be static or dynamic. The _static_ interface lets you display a notification’s message along with additional static text and images. The _dynamic_ interface gives you access to the notification’s full content and offers more options for configuring the appearance of the interface.
+
+You can customize the content area for both static and dynamic long looks, but you can’t change the overall structure of the interface. The system-defined structure includes a _sash_ at the top of the interface and a Dismiss button at the bottom, below all custom buttons.
+
+**Consider using a rich, custom long-look notification to let people get the information they need without launching your app.** You can use SwiftUI [Animations](https://developer.apple.com/documentation/SwiftUI/Animations) to create engaging, interruptible animations; alternatively, you can use [SpriteKit](https://developer.apple.com/documentation/SpriteKit) or [SceneKit](https://developer.apple.com/documentation/SceneKit).
+
+**At the minimum, provide a static interface; prefer providing a dynamic interface too.** The system defaults to the static interface when the dynamic interface is unavailable, such as when there is no network or the iPhone companion app is unreachable. Be sure to create the resources for your static interface in advance and package them with your app.
+
+**Choose a background appearance for the sash.** The system-provided sash, at the top of the long-look interface, displays your app icon and name. You can customize the sash’s color or give it a blurred appearance. If you display a photo at the top of the content area, you’ll probably want to use the blurred sash, which has a light, translucent appearance that gives the illusion of overlapping the image.
+
+**Choose a background color for the content area.** By default, the long look’s background is transparent. If you want to match the background color of other system notifications, use white with 18% opacity; otherwise, you can use a custom color, such as a color within your brand’s palette.
+
+**Provide up to four custom actions below the content area.** For each long look, the system uses the notification’s type to determine which of your custom actions to display as buttons in the notification UI. In addition, the system always displays a Dismiss button at the bottom of the long-look interface, below all custom buttons. If your watchOS app has an iPhone companion that supports notifications, the system shares the actionable notification types already registered by your iPhone app and uses them to configure your custom action buttons.
+
+#### [Double tap](https://developer.apple.com/design/human-interface-guidelines/notifications#Double-tap)
+
+People can double-tap to respond to notifications on supported devices. When a person responds to a notification with a double tap, the system selects the first nondestructive action as the response.
+
+**Keep double tap in mind when choosing the order of custom actions you present as responses to a notification.** Because a double tap runs the first nondestructive action, consider placing the action that people use most frequently at the top of the list. For example, a parking app that provides custom actions for extending the time on a paid parking spot could offer options to extend the time by 5 minutes, 15 minutes, or an hour, with the most common choice listed first.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/notifications#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/notifications#Related)
+
+[Managing notifications](https://developer.apple.com/design/human-interface-guidelines/managing-notifications)
+
+[Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/notifications#Developer-documentation)
+
+[Asking permission to use notifications](https://developer.apple.com/documentation/UserNotifications/asking-permission-to-use-notifications) — User Notifications
+
+[User Notifications UI](https://developer.apple.com/documentation/UserNotificationsUI)
+
+[User Notifications](https://developer.apple.com/documentation/UserNotifications)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/notifications#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/B63A08EA-8856-4C77-9E1B-EA1CAD990619/4986_wide_250x141_1x.jpg) Send communication and Time Sensitive notifications ](https://developer.apple.com/videos/play/wwdc2021/10091)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/49/3D8237BC-06E3-4711-8552-7008A5D5BAAD/3764_wide_250x141_1x.jpg) The Push Notifications primer ](https://developer.apple.com/videos/play/wwdc2020/10095)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/notifications#Change-log)
+
+Date| Changes  
+---|---  
+October 24, 2023| Updated watchOS platform considerations with guidance for presenting notification responses to double tap.  
+  

package/skills/hig-components-system/references/top-shelf.md

@@ -0,0 +1,135 @@
+---
+title: "Top Shelf | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/top-shelf
+
+# Top Shelf
+
+The Apple TV Home Screen provides an area called Top Shelf, which showcases your content in a rich, engaging way while also giving people access to their favorite apps in the Dock.
+
+![A stylized representation of a horizontal list of media previews above rows of Apple TV apps. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/73359c0fed7c9f8fd20b9a2c03ebfe66/components-top-shelf-intro%402x.png)
+
+When you support full-screen Top Shelf, people can swipe through multiple full-screen content views, play trailers and previews, and get more information about your content.
+
+Top Shelf is a unique opportunity to highlight new, featured, or recommended content and let people jump directly to your app or game to view it. For example, when people select Apple TV in the Dock, full-screen previews immediately begin playing and soon the Dock slides away. As people watch previews for the first show, they can swipe through previews of all other featured shows, stopping to select Play or More Info for a preview that interests them.
+
+The system defines several layout templates that you can use to give people a compelling Top Shelf experience when they select your app in the Dock. To help you position content, you can download these templates from [Apple Design Resources](https://developer.apple.com/design/resources/#tvos-apps).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Best-practices)
+
+**Help people jump right into your content.** Top Shelf provides a path to the content people care about most. Two of the system-provided layout templates — [carousel actions](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Carousel-actions) and [carousel details](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Carousel-details) — each include two buttons by default: A primary button intended to begin playback and a More Info button intended to open your app to a view that displays details about the content.
+
+**Feature new content.** For example, showcase new releases or episodes, highlight upcoming movies and shows, and avoid promoting content that people have already purchased, rented, or watched.
+
+**Personalize people’s favorite content.** People typically put the apps they use most often into Top Shelf. You can personalize their experience by showing targeted recommendations in the Top Shelf content you supply, letting people resume media playback or jump back into active gameplay.
+
+**Avoid showing advertisements or prices.** People put your app into Top Shelf because you’ve already sold them on it, so they may not appreciate seeing lots of ads from your app. Showing purchasable content in the Top Shelf is fine, but prefer putting the focus on new and exciting content, and consider displaying prices only when people show interest.
+
+**Showcase compelling dynamic content that can help draw people in and encourage them to view more.** If necessary, you can supply static images, but people typically prefer a captivating, dynamic Top Shelf experience that features the newest or highest rated content. To provide this experience, prefer creating [layered images](https://developer.apple.com/design/human-interface-guidelines/images#Layered-images) to display in Top Shelf.
+
+**If you don’t provide the recommended full-screen content, supply at least one static image as a fallback.** The system displays a static image when your app is in the Dock and in focus and full-screen content is unavailable. tvOS flips and blurs the image, ensuring that it fits into a width of 1920 pixels at the 16:9 aspect ratio. Use the following values for guidance.
+
+Image size  
+---  
+2320x720 pt (2320x720 px @1x, 4640x1440 px @2x)  
+  
+**Avoid implying interactivity in a static image.** A static Top Shelf image isn’t focusable, and you don’t want to make people think it’s interactive.
+
+## [Dynamic layouts](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Dynamic-layouts)
+
+Dynamic Top Shelf images can appear in several ways:
+
+  * A carousel of full-screen video and images that includes two buttons and optional details
+
+  * A row of focusable content
+
+  * A set of scrolling banners
+
+
+
+
+### [Carousel actions](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Carousel-actions)
+
+The carousel actions layout style focuses on full-screen video and images and includes a few unobtrusive controls that help people see more. This layout style works especially well to showcase content that people already know something about. For example, it’s great for displaying user-generated content, like photos, or new content from a franchise or show that people are likely to enjoy.
+
+**Provide a title.** Include a succinct title, like the title of the show or movie or the title of a photo album. If necessary, you can also provide a brief subtitle. For example, a subtitle for a photo album could be a range of dates; a subtitle for an episode could be the name of the show.
+
+### [Carousel details](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Carousel-details)
+
+This layout style extends the carousel actions layout style, giving you the opportunity to include some information about the content. For example, you might provide information like a plot summary, cast list, and other metadata that helps people decide whether to choose the content.
+
+**Provide a title that identifies the currently playing content.** The content title appears near the top of the screen so it’s easy for people to read it at a glance. Above the title, you can also provide a succinct phrase or app attribution, like “Featured on _My App_.”
+
+### [Sectioned content row](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Sectioned-content-row)
+
+This layout style shows a single labeled row of sectioned content, which can work well to highlight recently viewed content, new content, or favorites. Row content is focusable, which lets people scroll quickly through it. A label appears when an individual piece of content comes into focus, and small movements on the remote’s Touch surface bring the focused image to life. You can also configure a sectioned content row to show multiple labels.
+
+**Provide enough content to constitute a complete row.** At a minimum, load enough images in a sectioned content row to span the full width of the screen. In addition, include at least one label for greater platform consistency and to provide additional context.
+
+You can use the following image sizes in a sectioned content row.
+
+#### [Poster (2:3)](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Poster-23)
+
+![An illustration showing an outlined rectangle that contains a slightly smaller rectangle, which contains a slight narrower rectangle. The outermost rectangle represents the actual size, the middle rectangle represents the visible or safe zone, and the innermost rectangle represents the unfocused size.](https://docs-assets.developer.apple.com/published/13d162f243a286d45bb107b4a7cb799b/icons-and-images-content-layout-2x3%402x.png)
+
+Aspect| Image size  
+---|---  
+Actual size| 404x608 pt (404x608 px @1x, 808x1216 px @2x)  
+Focused/Safe zone size| 380x570 pt (380x570 px @1x, 760x1140 px @2x)  
+Unfocused size| 333x570 pt (333x570 px @1x, 666x1140 px @2x)  
+  
+#### [Square (1:1)](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Square-11)
+
+![An illustration showing an outlined square that contains a slightly smaller square, which contains a slightly smaller square. The outermost  square represents the actual size, the middle square represents the visible or safe zone, and the innermost square represents the unfocused size.](https://docs-assets.developer.apple.com/published/eba53b409d9ed6226c9b1e965dc17033/icons-and-images-content-layout-1x1%402x.png)
+
+Aspect| Image size  
+---|---  
+Actual size| 608x608 pt (608x608 px @1x, 1216x1216 px @2x)  
+Focused/Safe zone size| 570x570 pt (570x570 px @1x, 1140x1140 px @2x)  
+Unfocused size| 500x500 pt (500x500 px @1x, 1000x1000 px @2x)  
+  
+#### [16:9](https://developer.apple.com/design/human-interface-guidelines/top-shelf#169)
+
+![An illustration showing an outlined rectangle that contains a slightly smaller rectangle, which contains a slightly smaller rectangle. The outermost rectangle represents the actual size, the middle rectangle represents the visible or safe zone, and the innermost rectangle represents the unfocused size.](https://docs-assets.developer.apple.com/published/2b45c73a75fdeafef21cbb3c2923259a/icons-and-images-content-layout-16x9%402x.png)
+
+Aspect| Image size  
+---|---  
+Actual size| 908x512 pt (908x512 px @1x, 1816x1024 px @2x)  
+Focused/Safe zone size| 852x479 pt (852x479 px @1x, 1704x958 px @2x)  
+Unfocused size| 782x440 pt (782x440 px @1x, 1564x880 px @2x)  
+  
+**Be aware of additional scaling when combining image sizes.** If your Top Shelf design includes a mixture of image sizes, keep in mind that images will automatically scale up to match the height of the tallest image if necessary. For example, a 16:9 image scales to 500 pixels high if included in a row with a poster or square image.
+
+#### [Scrolling inset banner](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Scrolling-inset-banner)
+
+This layout shows a series of large images, each of which spans almost the entire width of the screen. Apple TV automatically scrolls through these banners on a preset timer until people bring one into focus. The sequence circles back to the beginning after the final image is reached.
+
+When a banner is in focus, a small, circular gesture on the remote’s Touch surface enacts the system focus effect, animating the item, applying lighting effects, and, if the banner contains layered images, producing a 3D effect. Swiping on the Touch surface pans to the next or previous banner in the sequence. Use this style to showcase rich, captivating content, such as a popular new movie.
+
+**Provide three to eight images.** A minimum of three images is recommended for a scrolling banner to feel effective. More than eight images can make it hard to navigate to a specific image.
+
+**If you need text, add it to your image.** This layout style doesn’t show labels under content, so all text must be part of the image itself. In layered images, consider elevating text by placing it on a dedicated layer above the others. Add the text to the accessibility label of the image too, so [VoiceOver](https://developer.apple.com/design/human-interface-guidelines/voiceover) can read it.
+
+![An illustration showing a wide rectangle that contains of a smaller rectangle, which contains a slightly narrower rectangle. The outermost rectangle represents the actual size, the middle rectangle represents the visible or safe zone, and the innermost rectangle represents the unfocused size.](https://docs-assets.developer.apple.com/published/e7ca852b559e9d981c968703dbad0315/icons-and-images-content-layout-extra-wide%402x.png)
+
+Use the following size for a scrolling inset banner image:
+
+Aspect| Image size  
+---|---  
+Actual size| 1940x692 pt (1940x692 px @1x, 3880x1384 px @2x)  
+Focused/Safe zone size| 1740x620 pt (1740x620 px @1x, 3480x1240 px @2x)  
+Unfocused size| 1740x560 pt (1740x560 px @1x, 3480x1120 px @2x)  
+  
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, macOS, visionOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Related)
+
+[Apple Design Resources](https://developer.apple.com/design/resources/#tvos-apps)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/top-shelf#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/48/21CB7C2D-31A3-4DE5-A0EE-58FE214031F0/2713_wide_250x141_1x.jpg) Mastering the Living Room With tvOS ](https://developer.apple.com/videos/play/wwdc2019/211)
+

package/skills/hig-components-system/references/watch-faces.md

@@ -0,0 +1,40 @@
+---
+title: "Watch faces | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/watch-faces
+
+# Watch faces
+
+A watch face is a view that people choose as their primary view in watchOS.
+
+![A stylized representation of a series of Apple Watch faces. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/bdf9c3962f71506a149c0ee448c2a0ad/components-faces-intro%402x.png)
+
+The watch face is at the heart of the watchOS experience. People choose a watch face they want to see every time they raise their wrist, and they customize it with their favorite complications. People can even customize different watch faces for different activities, so they can switch to the watch face that fits their current context.
+
+In watchOS 7 and later, people can share the watch faces they configure. For example, a fitness instructor might configure a watch face to share with their students by choosing the Gradient watch face, customizing the color, and adding their favorite health and fitness complications. When the students add the shared watch face to their Apple Watch or the Watch app on their iPhone, they get a custom experience without having to configure it themselves.
+
+You can also configure a watch face to share from within your app, on your website, or through Messages, Mail, or social media. Offering shareable watch faces can help you introduce more people to your complications and your app.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/watch-faces#Best-practices)
+
+**Help people discover your app by sharing watch faces that feature your complications.** Ideally, you support multiple complications so that you can showcase them in a shareable watch face and provide a curated experience. For some watch faces, you can also specify a system accent color, images, or styles. If people add your watch face but haven’t installed your app, the system prompts them to install it.
+
+**Display a preview of each watch face you share.** Displaying a preview that highlights the advantages of your watch face can help people visualize its benefits. You can get a preview by using the iOS Watch app to email the watch face to yourself. The preview includes an illustrated device bezel that frames the face and is suitable for display on websites and in watchOS and iOS apps. Alternatively, you can replace the illustrated bezel with a high-fidelity hardware bezel that you can download from [Apple Design Resources](https://developer.apple.com/design/resources/#product-bezels) and composite onto the preview. For developer guidance, see [Sharing an Apple Watch face](https://developer.apple.com/documentation/ClockKit/sharing-an-apple-watch-face).
+
+**Aim to offer shareable watch faces for all Apple Watch devices.** Some watch faces are available on Series 4 and later — such as California, Chronograph Pro, Gradient, Infograph, Infograph Modular, Meridian, Modular Compact, and Solar Dial — and Explorer is available on Series 3 (with cellular) and later. If you use one of these faces in your configuration, consider offering a similar configuration using a face that’s available on Series 3 and earlier. To help people make a choice, you can clearly label each shareable watch face with the devices it supports.
+
+**Respond gracefully if people choose an incompatible watch face.** The system sends your app an error when people try to use an incompatible watch face on Series 3 or earlier. In this scenario, consider immediately offering an alternative configuration that uses a compatible face instead of displaying an error. Along with the previews you provide, help people understand that they might receive an alternative watch face if they choose a face that isn’t compatible with their Apple Watch.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/watch-faces#Platform-considerations)
+
+ _Not supported in iOS, iPadOS, macOS, tvOS, or visionOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/watch-faces#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/watch-faces#Related)
+
+[Apple Design Resources — Product Bezels](https://developer.apple.com/design/resources/#product-bezels)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/watch-faces#Developer-documentation)
+
+[Sharing an Apple Watch face](https://developer.apple.com/documentation/ClockKit/sharing-an-apple-watch-face) — ClockKit
+