@ngxtm/devkit 3.15.0 → 3.17.0

package/skills/hig-foundations/references/dark-mode.md

@@ -0,0 +1,116 @@
+---
+title: "Dark Mode | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/dark-mode
+
+# Dark Mode
+
+Dark Mode is a systemwide appearance setting that uses a dark color palette to provide a comfortable viewing experience tailored for low-light environments.
+
+![A sketch of concentric circles with half-filled areas, suggesting the presence of light and dark. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/f354bd96f1890df83e7f8e31835f80bc/foundations-dark-mode-intro%402x.png)
+
+In iOS, iPadOS, macOS, and tvOS, people often choose Dark Mode as their default interface style, and they generally expect all apps and games to respect their preference. In Dark Mode, the system uses a dark color palette for all screens, views, menus, and controls, and may also use greater perceptual contrast to make foreground content stand out against the darker backgrounds.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Best-practices)
+
+**Avoid offering an app-specific appearance setting.** An app-specific appearance mode option creates more work for people because they have to adjust more than one setting to get the appearance they want. Worse, they may think your app is broken because it doesn’t respond to their systemwide appearance choice.
+
+**Ensure that your app looks good in both appearance modes.** In addition to using one mode or the other, people can choose the Auto appearance setting, which switches between the light and dark appearances as conditions change throughout the day, potentially while your app is running.
+
+**Test your content to make sure that it remains comfortably legible in both appearance modes.** For example, in Dark Mode with Increase Contrast and Reduce Transparency turned on (both separately and together), you may find places where dark text is less legible when it’s on a dark background. You might also find that turning on Increase Contrast in Dark Mode can result in reduced visual contrast between dark text and a dark background. Although people with strong vision might still be able to read lower contrast text, such text could be illegible for many. For guidance, see [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility).
+
+**In rare cases, consider using only a dark appearance in the interface.** For example, it can make sense for an app that supports immersive media viewing to use a permanently dark appearance that lets the UI recede and helps people focus on the media.
+
+![A screenshot of the Stocks app on iPhone in its standard dark-only appearance, showing the Apple Inc. stock in detail. The view includes a summary of the current stock price along with a graph of its performance over the past year.](https://docs-assets.developer.apple.com/published/50e3d01e38e69e84976f7a1747321ba8/dark-mode-stocks-app-dark-only-mode%402x.png)
+
+The Stocks app uses a dark-only appearance
+
+## [Dark Mode colors](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Dark-Mode-colors)
+
+The color palette in Dark Mode includes dimmer background colors and brighter foreground colors. It’s important to realize that these colors aren’t necessarily inversions of their light counterparts: while many colors are inverted, some are not. For more information, see [Specifications](https://developer.apple.com/design/human-interface-guidelines/color#Specifications).
+
+**Embrace colors that adapt to the current appearance.** Semantic colors (like [`labelColor`](https://developer.apple.com/documentation/AppKit/NSColor/labelColor) and [`controlColor`](https://developer.apple.com/documentation/AppKit/NSColor/controlColor) in macOS or [`separator`](https://developer.apple.com/documentation/UIKit/UIColor/separator) in iOS and iPadOS) automatically adapt to the current appearance. When you need a custom color, add a Color Set asset to your app’s asset catalog in Xcode, and specify the bright and dim variants of the color. Avoid using hard-coded color values or colors that don’t adapt.
+
+![An illustration of a square with a light background and four color swatches representing system colors in the light appearance.](https://docs-assets.developer.apple.com/published/083d8f0f70c26b7fdea230f7da1edfeb/dark-mode-system-colors-light%402x.png)System colors in the light appearance
+
+![An illustration of a square with a dark background and four color swatches representing system colors in the dark appearance.](https://docs-assets.developer.apple.com/published/247df4f7b00e65cdd3827de84135fcda/dark-mode-system-colors-dark%402x.png)System colors in the dark appearance
+
+**Aim for sufficient color contrast in all appearances.** Using system-defined colors can help you achieve a good contrast ratio between your foreground and background content. At a minimum, make sure the contrast ratio between colors is no lower than 4.5:1. For custom foreground and background colors, strive for a contrast ratio of 7:1, especially in small text. This ratio ensures that your foreground content stands out from the background, and helps your content meet recommended accessibility guidelines.
+
+**Soften the color of white backgrounds.** If you display a content image that includes a white background, consider slightly darkening the image to prevent the background from glowing in the surrounding Dark Mode context.
+
+### [Icons and images](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Icons-and-images)
+
+The system uses [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) (which automatically adapt to Dark Mode) and full-color images that are optimized for both the light and dark appearances.
+
+**Use SF Symbols wherever possible.** Symbols work well in both appearance modes when you use dynamic colors to tint them or when you add vibrancy. For guidance, see [Color](https://developer.apple.com/design/human-interface-guidelines/color).
+
+**Design separate interface icons for the light and dark appearances if necessary.** For example, an icon that depicts a full moon might need a subtle dark outline to contrast well with a light background, but need no outline when it displays on a dark background. Similarly, an icon that represents a drop of oil might need a slight border to make the edge visible against a dark background.
+
+![An illustration of a black droplet icon against a light background.](https://docs-assets.developer.apple.com/published/5377a16f9c47c32d5716a2de9e7e5ddb/dark-mode-icon-in-light-mode%402x.png)Icon in the light appearance with no border
+
+![An illustration of a black droplet icon against a dark background. The icon has a white border to distinguish it from the similar surrounding color.](https://docs-assets.developer.apple.com/published/a2ebe256a3e677367cc3e965e8282168/dark-mode-icon-in-dark-mode%402x.png)Icon in the dark appearance with border for better contrast
+
+**Make sure full-color images and icons look good in both appearances.** Use the same asset if it looks good in both the light and dark appearances. If an asset looks good in only one mode, modify the asset or create separate light and dark assets. Use asset catalogs to combine your assets into a single named image.
+
+![An illustration of two people sitting at a restaurant table done in a simple, abstract style. The illustration has a light background and its details are clearly visible.](https://docs-assets.developer.apple.com/published/017a90f0e42a841edec3d4238f408e9e/dark-mode-illustration-in-light-mode%402x.png)Illustration on a light background
+
+![An illustration of two people sitting at a restaurant table done in a simple, abstract style. The illustration has a dark background, and the darker portions of the image are hard to distinguish from the background.](https://docs-assets.developer.apple.com/published/97c07bc517069bf9175e7a3374ed95aa/dark-mode-illustration-in-dark-mode-incorrect%402x.png)On a dark background, the same illustration has poor contrast and many details are lost
+
+![An illustration of two people sitting at a restaurant table done in a simple, abstract style. The illustration has a dark background, and its color values are adjusted to be clearly visible in contrast to the background.](https://docs-assets.developer.apple.com/published/fa4aec31ae33aadce2ed0a0434c9c605/dark-mode-illustration-in-dark-mode-correct%402x.png)Illustration adjusted for better contrast on a dark background
+
+### [Text](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Text)
+
+The system uses vibrancy and increased contrast to maintain the legibility of text on darker backgrounds.
+
+**Use the system-provided label colors for labels.** The primary, secondary, tertiary, and quaternary label colors adapt automatically to the light and dark appearances.
+
+![An illustration of a button in the light appearance with dark primary label text.](https://docs-assets.developer.apple.com/published/4dc33e45cd6cae3da766f885044174e9/dark-mode-label-in-light-mode%402x.png)Primary label in the light appearance
+
+![An illustration of a button in the dark appearance with light secondary label text.](https://docs-assets.developer.apple.com/published/5a2df784b29a55d1db485c30efb94009/dark-mode-label-in-dark-mode%402x.png)Secondary label in the dark appearance
+
+**Use system views to draw text fields and text views.** System views and controls make your app’s text look good on all backgrounds, adjusting automatically for the presence or absence of vibrancy. When possible, use a system-provided view to display text instead of drawing the text yourself.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Platform-considerations)
+
+ _No additional considerations for tvOS. Dark Mode isn’t supported in visionOS or watchOS._
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/dark-mode#iOS-iPadOS)
+
+In Dark Mode, the system uses two sets of background colors — called _base_ and _elevated_ — to enhance the perception of depth when one dark interface is layered above another. The base colors are dimmer, making background interfaces appear to recede, and the elevated colors are brighter, making foreground interfaces appear to advance.
+
+![A diagram that shows a stack of 4 terms on top of a black background. The term at the top shows the most contrast with the background and the term at the bottom shows the least.](https://docs-assets.developer.apple.com/published/0d71ac9f5186541dce35b5f702311bd0/base-with-four-semantic-colors%402x.png)Base
+
+![A diagram that shows a stack of 4 terms on top of a nearly black background. The term at the top shows the most contrast with the background and the term at the bottom shows the least.](https://docs-assets.developer.apple.com/published/0dacc182adc819b08eb8cdcc897b08a4/elevated-with-four-semantic-colors%402x.png)Elevated
+
+![A diagram that shows a stack of 4 terms on top of a white background. The term at the top shows the most contrast with the background and the term at the bottom shows the least.](https://docs-assets.developer.apple.com/published/cbbe9a39049fd3d3d2122876de64d207/light-with-four-semantic-colors%402x.png)Light
+
+**Prefer the system background colors.** Dark Mode is dynamic, which means that the background color automatically changes from base to elevated when an interface is in the foreground, such as a popover or modal sheet. The system also uses the elevated background color to provide visual separation between apps in a multitasking environment and between windows in a multiple-window context. Using a custom background color can make it harder for people to perceive these system-provided visual distinctions.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/dark-mode#macOS)
+
+When people choose the graphite accent color in General settings, macOS causes window backgrounds to pick up color from the current desktop picture. The result — called _desktop tinting_ — is a subtle effect that helps windows blend more harmoniously with their surrounding content.
+
+**Include some transparency in custom component backgrounds when appropriate.** Transparency lets your components pick up color from the window background when desktop tinting is active, creating a visual harmony that can persist even when the desktop picture changes. To help achieve this harmony, add transparency only to a custom component that has a visible background or bezel, and only when the component is in a neutral state, such as state that doesn’t use color. You don’t want to add transparency when the component is in a state that uses color, because doing so can cause the component’s color to fluctuate when the window background adjusts to a different location on the desktop or when the desktop picture changes.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Related)
+
+[Color](https://developer.apple.com/design/human-interface-guidelines/color)
+
+[Materials](https://developer.apple.com/design/human-interface-guidelines/materials)
+
+[Typography](https://developer.apple.com/design/human-interface-guidelines/typography)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/5CD0E251-424E-490F-89CF-1E64848209A6/9910_wide_250x141_1x.jpg) Meet Liquid Glass ](https://developer.apple.com/videos/play/wwdc2025/219)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/48/174747D6-8723-4194-A932-7765179F1108/2949_wide_250x141_1x.jpg) Implementing Dark Mode on iOS ](https://developer.apple.com/videos/play/wwdc2019/214)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/dark-mode#Change-log)
+
+Date| Changes  
+---|---  
+August 6, 2024| Added art contrasting the light and dark appearances.  
+  

package/skills/hig-foundations/references/icons.md

@@ -0,0 +1,263 @@
+---
+title: "Icons | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/icons
+
+# Icons
+
+An effective icon is a graphic asset that expresses a single concept in ways people instantly understand.
+
+![A sketch of the Command key icon. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/e71f139e5e50d9d10d91830b0af405c1/foundations-icons-intro%402x.png)
+
+Apps and games use a variety of simple icons to help people understand the items, actions, and modes they can choose. Unlike [app icons](https://developer.apple.com/design/human-interface-guidelines/app-icons), which can use rich visual details like shading, texturing, and highlighting to evoke the app’s personality, an _interface icon_ typically uses streamlined shapes and touches of color to communicate a straightforward idea.
+
+You can design interface icons — also called _glyphs_ — or you can choose symbols from the SF Symbols app, using them as-is or customizing them to suit your needs. Both interface icons and symbols use black and clear colors to define their shapes; the system can apply other colors to the black areas in each image. For guidance, see [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/icons#Best-practices)
+
+**Create a recognizable, highly simplified design.** Too many details can make an interface icon confusing or unreadable. Strive for a simple, universal design that most people will recognize quickly. In general, icons work best when they use familiar visual metaphors that are directly related to the actions they initiate or content they represent.
+
+**Maintain visual consistency across all interface icons in your app.** Whether you use only custom icons or mix custom and system-provided ones, all interface icons in your app need to use a consistent size, level of detail, stroke thickness (or weight), and perspective. Depending on the visual weight of an icon, you may need to adjust its dimensions to ensure that it appears visually consistent with other icons.
+
+![Diagram of four glyphs in a row. From the left, the glyphs are a camera, a heart, an envelope, and an alarm clock. Two horizontal dashed lines show the bottom and top boundaries of the row and a horizontal red line shows the midpoint. All four glyphs are solid black; some include interior detail lines in white. Parts of the alarm clock extend above the top dashed line because its lighter visual weight requires greater height to achieve balance with the other glyphs.](https://docs-assets.developer.apple.com/published/f1cf8ce0ca53b7cb3bce1391a378f6ce/custom-icon-sizes%402x.png)To help achieve visual consistency, adjust individual icon sizes as necessary…
+
+![Diagram of the same four glyphs shown above and the same horizontal dashed lines at top and bottom and horizontal red line through the middle. In this diagram, all four glyphs are solid gray; the interior detail lines are black to emphasize that all lines use the same weight.](https://docs-assets.developer.apple.com/published/91320cdd7a31574df355383d83eb1ceb/custom-icon-line-weights%402x.png)…and use the same stroke weight in every icon.
+
+**In general, match the weights of interface icons and adjacent text.** Unless you want to emphasize either the icons or the text, using the same weight for both gives your content a consistent appearance and level of emphasis.
+
+**If necessary, add padding to a custom interface icon to achieve optical alignment.** Some icons — especially asymmetric ones — can look unbalanced when you center them geometrically instead of optically. For example, the download icon shown below has more visual weight on the bottom than on the top, which can make it look too low if it’s geometrically centered.
+
+![Two images of a white arrow that points down to a white horizontal line segment within a black disk. The image on the right includes two horizontal pink bars — one between the top of the glyph and the top of the disk and the other between the bottom of the glyph and the bottom of the disk — that show the glyph is geometrically centered within the disk.](https://docs-assets.developer.apple.com/published/1c13eed753a1ebcfd6d35929738476c7/asymmetric-glyph%402x.png)An asymmetric icon can look off center even though it’s not.
+
+In such cases, you can slightly adjust the position of the icon until it’s optically centered. When you create an asset that includes your adjustments as padding around an interface icon (as shown below on the right), you can optically center the icon by geometrically centering the asset.
+
+![Two images of a white arrow that points down to a white horizontal line segment within a black disk. The image on the left includes the two horizontal pink bars in the same locations as in the previous illustration, but the glyph has been moved up by a few pixels. The image on the right includes a pink rectangle overlaid on top of the glyph to represent a padding area, which includes the extra pixels below the glyph.](https://docs-assets.developer.apple.com/published/c31bce31456820badff997c95db264c6/asymmetric-glyph-optically-centered%402x.png)Moving the icon a few pixels higher optically centers it; including the pixels in padding simplifies centering.
+
+Adjustments for optical centering are typically very small, but they can have a big impact on your app’s appearance.
+
+![Two images of a white arrow that points down to a white horizontal line segment within a black disk. The glyph on the left is geometrically centered and the one on the right is optically centered.](https://docs-assets.developer.apple.com/published/5d9da37476ee3225a29ce3efbfd86cac/asymmetric-glyph-before-and-after%402x.png)Before optical centering (left) and after optical centering (right).
+
+**Provide a selected-state version of an interface icon only if necessary.** You don’t need to provide selected and unselected appearances for an icon that’s used in standard system components such as toolbars, tab bars, and buttons. The system updates the visual appearance of the selected state automatically.
+
+![An image of two toolbar buttons that share a background. The left button shows the Filter icon in a selected state, using a blue tint color for its background. The right button shows the More icon in an unselected state, using the default appearance for toolbar buttons.](https://docs-assets.developer.apple.com/published/b5c874fca24c428b421c008b29709986/icons-selection-correct%402x.png)In a toolbar, a selected icon receives the app’s accent color.
+
+**Use inclusive images.** Consider how your icons can be understandable and welcoming to everyone. Prefer depicting gender-neutral human figures and avoid images that might be hard to recognize across different cultures or languages. For guidance, see [Inclusion](https://developer.apple.com/design/human-interface-guidelines/inclusion).
+
+**Include text in your design only when it’s essential for conveying meaning.** For example, using a character in an interface icon that represents text formatting can be the most direct way to communicate the concept. If you need to display individual characters in your icon, be sure to localize them. If you need to suggest a passage of text, design an abstract representation of it, and include a flipped version of the icon to use when the context is right-to-left. For guidance, see [Right to left](https://developer.apple.com/design/human-interface-guidelines/right-to-left).
+
+![A partial screenshot of the SF Symbols app showing the info panel for the character symbol, which looks like the capital letter A. Below the image, the following eight localized versions of the symbol are listed: Latin, Arabic, Hebrew, Hindi, Japanese, Korean, Thai, and Chinese.](https://docs-assets.developer.apple.com/published/1037fd04c26206ca1b1dee2e34e123af/character-in-glyph%402x.png)Create localized versions of an icon that displays individual characters.
+
+![A partial screenshot of the SF Symbols app showing the info panel for the text dot page symbol, which looks like three left-aligned horizontal lines inside a rounded rectangle. Below the image, the left-to-right and right-to-left localized versions are shown.](https://docs-assets.developer.apple.com/published/2edc8ff4ae7af79f32543009ba2f7084/abstract-text-in-glyph%402x.png)Create a flipped version of an icon that suggests reading direction.
+
+**If you create a custom interface icon, use a vector format like PDF or SVG.** The system automatically scales a vector-based interface icon for high-resolution displays, so you don’t need to provide high-resolution versions of it. In contrast, PNG — used for app icons and other images that include effects like shading, textures, and highlighting — doesn’t support scaling, so you have to supply multiple versions for each PNG-based interface icon. Alternatively, you can create a custom SF Symbol and specify a scale that ensures the symbol’s emphasis matches adjacent text. For guidance, see [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols).
+
+**Provide alternative text labels for custom interface icons.** Alternative text labels — or accessibility descriptions — aren’t visible, but they let VoiceOver audibly describe what’s onscreen, simplifying navigation for people with visual disabilities. For guidance, see [VoiceOver](https://developer.apple.com/design/human-interface-guidelines/voiceover).
+
+**Avoid using replicas of Apple hardware products.** Hardware designs tend to change frequently and can make your interface icons and other content appear dated. If you must display Apple hardware, use only the images available in [Apple Design Resources](https://developer.apple.com/design/resources/) or the SF Symbols that represent various Apple products.
+
+## [Standard icons](https://developer.apple.com/design/human-interface-guidelines/icons#Standard-icons)
+
+For icons to represent common actions in [menus](https://developer.apple.com/design/human-interface-guidelines/menus), [toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars), [buttons](https://developer.apple.com/design/human-interface-guidelines/buttons), and other places in interfaces across Apple platforms, you can use these [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols).
+
+### [Editing](https://developer.apple.com/design/human-interface-guidelines/icons#Editing)
+
+Action| Icon| Symbol name  
+---|---|---  
+Cut| ![An icon showing a pair of scissors.](https://docs-assets.developer.apple.com/published/16c5fe84ae743e06cf2d388fc64e0cf4/icons-symbols-meaning-cut%402x.png)| `scissors`  
+Copy| ![An icon showing two copies of a document.](https://docs-assets.developer.apple.com/published/a88919c55265efbadeac0df5e16ffd05/icons-symbols-meaning-copy%402x.png)| `document.on.document`  
+Paste| ![An icon showing a document in front of a clipboard.](https://docs-assets.developer.apple.com/published/20e32bbb2a3a94eb35d01ddfa9c630e0/icons-symbols-meaning-paste%402x.png)| `document.on.clipboard`  
+Done| ![An icon showing a checkmark.](https://docs-assets.developer.apple.com/published/833bd3b8ccdf0e2fee0893b3858ddae5/icons-symbols-meaning-done-save%402x.png)| `checkmark `  
+Save  
+Cancel| ![An icon showing an X.](https://docs-assets.developer.apple.com/published/b834206c8d155bc1b0d9d17c206c6da3/icons-symbols-meaning-close-cancel%402x.png)| `xmark`  
+Close  
+Delete| ![An icon showing a trash can.](https://docs-assets.developer.apple.com/published/61f8368d02b05af22d3253a892ced7f3/icons-symbols-meaning-delete%402x.png)| `trash`  
+Undo| ![An icon showing an arrow curving toward the top left.](https://docs-assets.developer.apple.com/published/e3e973d07e4cfa983c92e37da5b3e104/icons-symbols-meaning-undo%402x.png)| `arrow.uturn.backward`  
+Redo| ![An icon showing an arrow curving toward the top right.](https://docs-assets.developer.apple.com/published/0f263db97ca2b7c31bbbd3cd5682d071/icons-symbols-meaning-redo%402x.png)| `arrow.uturn.forward`  
+Compose| ![An icon showing a pencil positioned over a square.](https://docs-assets.developer.apple.com/published/cfac914468b7fa2f287495f8644f3937/icons-symbols-meaning-compose%402x.png)| `square.and.pencil`  
+Duplicate| ![An icon showing a square with a plus sign on top of another square.](https://docs-assets.developer.apple.com/published/96323f746d3c67172648745420a15c27/icons-symbols-meaning-duplicate%402x.png)| `plus.square.on.square`  
+Rename| ![An icon showing a pencil.](https://docs-assets.developer.apple.com/published/8d3692b6e29cf0cdcb7885af414b2693/icons-symbols-meaning-rename%402x.png)| `pencil`  
+Move to| ![An icon showing a folder.](https://docs-assets.developer.apple.com/published/77c3e45c395bf2d2225c85979eca53a8/icons-symbols-meaning-move-to-folder%402x.png)| `folder`  
+Folder  
+Attach| ![An icon showing a paperclip.](https://docs-assets.developer.apple.com/published/e493eab83f8cc2a6f0aaa2ced386dcff/icons-symbols-meaning-attach%402x.png)| `paperclip`  
+Add| ![An icon showing a plus sign.](https://docs-assets.developer.apple.com/published/e0a7d36fc7aecfd6e49a4d0c0cb196af/icons-symbols-meaning-add%402x.png)| `plus`  
+More| ![An icon showing an ellipsis.](https://docs-assets.developer.apple.com/published/92e0b17a3881b62008563deb4a2aca40/icons-symbols-meaning-more%402x.png)| `ellipsis`  
+  
+### [Selection](https://developer.apple.com/design/human-interface-guidelines/icons#Selection)
+
+Action| Icon| Symbol name  
+---|---|---  
+Select| ![An icon showing a checkmark in a circle.](https://docs-assets.developer.apple.com/published/7eac493b5a3896062a90328117d43e90/icons-symbols-meaning-select-all%402x.png)| `checkmark.circle`  
+Deselect| ![An icon showing an X.](https://docs-assets.developer.apple.com/published/b834206c8d155bc1b0d9d17c206c6da3/icons-symbols-meaning-deselect-close%402x.png)| `xmark`  
+Close  
+Delete| ![An icon showing a trash can.](https://docs-assets.developer.apple.com/published/61f8368d02b05af22d3253a892ced7f3/icons-symbols-meaning-delete%402x.png)| `trash`  
+  
+### [Text formatting](https://developer.apple.com/design/human-interface-guidelines/icons#Text-formatting)
+
+Action| Icon| Symbol name  
+---|---|---  
+Superscript| ![An icon showing the capital letter A with the number 1 in the upper right corner.](https://docs-assets.developer.apple.com/published/7e5e3d9b1b0eb6f340f531841d6b27f9/icons-symbols-meaning-superscript%402x.png)| `textformat.superscript`  
+Subscript| ![An icon showing the capital letter A with the number 1 in the lower right corner.](https://docs-assets.developer.apple.com/published/aac330c124cac37a78e02d6049943e53/icons-symbols-meaning-subscript%402x.png)| `textformat.subscript`  
+Bold| ![An icon showing the capital letter B in bold.](https://docs-assets.developer.apple.com/published/c8695e06d6461e79c145e9b6627f70ac/icons-symbols-meaning-bold%402x.png)| `bold`  
+Italic| ![An icon showing the capital letter I in italics.](https://docs-assets.developer.apple.com/published/9f560283ff88d8d1d4b48f278a831b7b/icons-symbols-meaning-italic%402x.png)| `italic`  
+Underline| ![An icon showing the capital letter U with an underline.](https://docs-assets.developer.apple.com/published/3b0d371f10bde381bfa1c9a8999797ec/icons-symbols-meaning-underline%402x.png)| `underline`  
+​​Align Left| ![An icon showing a stack of four horizontal lines of varying widths that align at the left edge.](https://docs-assets.developer.apple.com/published/68c0ff42aa0ac813b57b663562198e15/icons-symbols-meaning-align-left%402x.png)| `text.alignleft`  
+Center| ![An icon showing a stack of four horizontal lines of varying widths that align in the center.](https://docs-assets.developer.apple.com/published/a10b48c850a047efd4a72cc2919c30da/icons-symbols-meaning-align-center%402x.png)| `text.aligncenter`  
+Justified| ![An icon showing a stack of four horizontal lines of identical widths.](https://docs-assets.developer.apple.com/published/d71f35b4f71149b0b908dd1ff8cfe01e/icons-symbols-meaning-align-justified%402x.png)| `text.justify`  
+Align Right| ![An icon showing a stack of four horizontal lines of varying widths that align at the right edge.](https://docs-assets.developer.apple.com/published/8af1da29f8f3173510521492642a82be/icons-symbols-meaning-align-right%402x.png)| `text.alignright`  
+  
+### [Search](https://developer.apple.com/design/human-interface-guidelines/icons#Search)
+
+Action| Icon| Symbol name  
+---|---|---  
+Search| ![An icon showing a magnifying glass.](https://docs-assets.developer.apple.com/published/585f5454757731f942979247bf886ecb/icons-symbols-meaning-search%402x.png)| `magnifyingglass`  
+Find| ![An icon showing a magnifying glass above a document.](https://docs-assets.developer.apple.com/published/646c6a152822dde685e52a2791ff672f/icons-symbols-meaning-find%402x.png)| `text.page.badge.magnifyingglass`  
+Find and Replace  
+Find Next  
+Find Previous  
+Use Selection for Find  
+Filter| ![An icon showing a stack of three horizontal lines decreasing in width from top to bottom.](https://docs-assets.developer.apple.com/published/e0924492d663dac952860673a61f4f96/icons-symbols-meaning-filter%402x.png)| `line.3.horizontal.decrease`  
+  
+### [Sharing and exporting](https://developer.apple.com/design/human-interface-guidelines/icons#Sharing-and-exporting)
+
+Action| Icon| Symbol name  
+---|---|---  
+Share| ![An icon showing an arrow pointing up from the middle of square.](https://docs-assets.developer.apple.com/published/b5fa28be3d82955fc380f44783befd32/icons-symbols-meaning-sharing%402x.png)| `square.and.arrow.up`  
+Export  
+Print| ![An icon showing a printer.](https://docs-assets.developer.apple.com/published/9de4d23e30e6fd8331215dd6dab12878/icons-symbols-meaning-print%402x.png)| `printer`  
+  
+### [Users and accounts](https://developer.apple.com/design/human-interface-guidelines/icons#Users-and-accounts)
+
+Action| Icon| Symbol name  
+---|---|---  
+Account| ![An icon showing an abstract representation of a person’s head and shoulders in a circular outline.](https://docs-assets.developer.apple.com/published/512c86a1c2c99bc09991c89c1e535441/icons-symbols-meaning-account-user%402x.png)| `person.crop.circle`  
+User  
+Profile  
+  
+### [Ratings](https://developer.apple.com/design/human-interface-guidelines/icons#Ratings)
+
+Action| Icon| Symbol name  
+---|---|---  
+Dislike| ![An icon showing a hand giving a thumbs down gesture.](https://docs-assets.developer.apple.com/published/189b97655ff655985deec03d0466b898/icons-symbols-meaning-dislike%402x.png)| `hand.thumbsdown`  
+Like| ![An icon showing a hand giving a thumbs up gesture.](https://docs-assets.developer.apple.com/published/6f38eef523ffbb4f1d6de22a6a022309/icons-symbols-meaning-like%402x.png)| `hand.thumbsup`  
+  
+### [Layer ordering](https://developer.apple.com/design/human-interface-guidelines/icons#Layer-ordering)
+
+Action| Icon| Symbol name  
+---|---|---  
+Bring to Front| ![An icon showing a stack of three squares overlapping each other, with the top square using a solid fill style while the other squares are outlines.](https://docs-assets.developer.apple.com/published/c5da334738c9baf5ddaa0d6ed9de0af6/icons-symbols-meaning-bring-to-front%402x.png)| `square.3.layers.3d.top.filled`  
+Send to Back| ![An icon showing a stack of three squares overlapping each other, with the bottom square using a solid fill style while the other squares are outlines.](https://docs-assets.developer.apple.com/published/1006037b6fa15950ca7ceb933dbb4805/icons-symbols-meaning-send-to-back%402x.png)| `square.3.layers.3d.bottom.filled`  
+Bring Forward| ![An icon showing a stack of two squares overlapping each other, with the top square using a solid fill style while the other square is an outline.](https://docs-assets.developer.apple.com/published/88b18e0384bca2cd93151169bd507aa3/icons-symbols-meaning-bring-forward%402x.png)| `square.2.layers.3d.top.filled`  
+Send Backward| ![An icon showing a stack of two squares overlapping each other, with the bottom square using a solid fill style while the other square is an outline.](https://docs-assets.developer.apple.com/published/49eb0ed5381249d763d30d4e515bc57b/icons-symbols-meaning-send-backwards%402x.png)| `square.2.layers.3d.bottom.filled`  
+  
+### [Other](https://developer.apple.com/design/human-interface-guidelines/icons#Other)
+
+Action| Icon| Symbol name  
+---|---|---  
+Alarm| ![An icon showing an alarm clock.](https://docs-assets.developer.apple.com/published/b777cb6bcc99642b037824c78a7efb0e/icons-symbols-meaning-alarm%402x.png)| `alarm`  
+Archive| ![An icon showing a file box.](https://docs-assets.developer.apple.com/published/50a3b677d72b3d031ea66d10198bfb59/icons-symbols-meaning-archive%402x.png)| `archivebox`  
+Calendar| ![An icon showing a calendar.](https://docs-assets.developer.apple.com/published/4b14bf07cf562405caebedb2e200e3dc/icons-symbols-meaning-calendar%402x.png)| `calendar`  
+  
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/icons#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, tvOS, visionOS, or watchOS._
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/icons#macOS)
+
+#### [Document icons](https://developer.apple.com/design/human-interface-guidelines/icons#Document-icons)
+
+If your macOS app can use a custom document type, you can create a document icon to represent it. Traditionally, a document icon looks like a piece of paper with its top-right corner folded down. This distinctive appearance helps people distinguish documents from apps and other content, even when icon sizes are small.
+
+If you don’t supply a document icon for a file type you support, macOS creates one for you by compositing your app icon and the file’s extension onto the canvas. For example, Preview uses a system-generated document icon to represent JPG files.
+
+![An image of the Preview document icon for a JPG file.](https://docs-assets.developer.apple.com/published/bfe462604c63811cb542e7c0fc46185e/doc-icon-generated%402x.png)
+
+In some cases, it can make sense to create a set of document icons to represent a range of file types your app handles. For example, Xcode uses custom document icons to help people distinguish projects, AR objects, and Swift code files.
+
+![Image of an Xcode project document icon.](https://docs-assets.developer.apple.com/published/8cd56a7291cd6b41fe391958f704c823/doc-icon-custom-1%402x.png)
+
+![Image of a document icon for an AR object.](https://docs-assets.developer.apple.com/published/a1449177968f693c1bd68c2b146df7c3/doc-icon-custom-2%402x.png)
+
+![Image of a document icon for a Swift file.](https://docs-assets.developer.apple.com/published/495bd043bf65349ec96f6728941386f8/doc-icon-custom-3%402x.png)
+
+To create a custom document icon, you can supply any combination of background fill, center image, and text. The system layers, positions, and masks these elements as needed and composites them onto the familiar folded-corner icon shape.
+
+![A square canvas that contains a grid of pink lines and a jagged white EKG line that runs horizontally across the middle. The pink grid gets lighter in color toward the bottom edge.](https://docs-assets.developer.apple.com/published/2aed446834a2dc6e8275b6bd7a797ca9/doc-icon-parts-background-fill%402x.png)Background fill
+
+![A solid pink heart.](https://docs-assets.developer.apple.com/published/b59c836903d1b409ab9e21f81762df3e/doc-icon-parts-center-image%402x.png)Center image
+
+![The word heart in all caps.](https://docs-assets.developer.apple.com/published/56c5adedc0c08a167a4a03e706924ee6/doc-icon-parts-text%402x.png)Text
+
+![A custom document icon that displays the pink heart and the word heart on top of the pink grid and white EKG line.](https://docs-assets.developer.apple.com/published/d5da9148d27f60891780ab1a9546a111/doc-icon-parts%402x.png)macOS composites the elements you supply to produce your custom document icon.
+
+[Apple Design Resources](https://developer.apple.com/design/resources/#macos-apps) provides a template you can use to create a custom background fill and center image for a document icon. As you use this template, follow the guidelines below.
+
+**Design simple images that clearly communicate the document type.** Whether you use a background fill, a center image, or both, prefer uncomplicated shapes and a reduced palette of distinct colors. Your document icon can display as small as 16x16 px, so you want to create designs that remain recognizable at every size.
+
+**Designing a single, expressive image for the background fill can be a great way to help people understand and recognize a document type.** For example, Xcode and TextEdit both use rich background images that don’t include a center image.
+
+![Image of an Xcode project document icon.](https://docs-assets.developer.apple.com/published/8cd56a7291cd6b41fe391958f704c823/doc-icon-custom-1%402x.png)
+
+![Image of a TextEdit rich text document icon.](https://docs-assets.developer.apple.com/published/f32709a5ff5742e79fd03a58ae1dd9c6/doc-icon-fill-only%402x.png)
+
+**Consider reducing complexity in the small versions of your document icon.** Icon details that are clear in large versions can look blurry and be hard to recognize in small versions. For example, to ensure that the grid lines in the custom heart document icon remain clear in intermediate sizes, you might use fewer lines and thicken them by aligning them to the reduced pixel grid. In the 16x16 px size, you might remove the lines altogether.
+
+![Pixelated image of the heart document icon. The grid, the EKG line, the heart shape, and the word heart are visible but blurry.](https://docs-assets.developer.apple.com/published/1f8bc7946a75363224f373924b557a3a/doc-icon-fewer-details-1%402x.png)The 32x32 px icon has fewer grid lines and a thicker EKG line.
+
+![Pixelated image of the heart document icon, in which only the blurry heart shape and EKG line are visible.](https://docs-assets.developer.apple.com/published/e46ac887801d9a16393948c3f2098715/doc-icon-fewer-details-2%402x.png)The 16x16 px @2x icon retains the EKG line but has no grid lines.
+
+![Pixelated image of the heart document icon, in which only the blurry heart shape is visible.](https://docs-assets.developer.apple.com/published/fd0d2afcd76a9b25c1217ef2ffb1ad0e/doc-icon-fewer-details-3%402x.png)The 16x16 px @1x icon has no EKG line and no grid lines.
+
+**Avoid placing important content in the top-right corner of your background fill.** The system automatically masks your image to fit the document icon shape and draws the white folded corner on top of the fill. Create a set of background images in the sizes listed below.
+
+  * 512x512 px @1x, 1024x1024 px @2x
+
+  * 256x256 px @1x, 512x512 px @2x
+
+  * 128x128 px @1x, 256x256 px @2x
+
+  * 32x32 px @1x, 64x64 px @2x
+
+  * 16x16 px @1x, 32x32 px @2x
+
+
+
+
+**If a familiar object can convey a document’s type or its connection with your app, consider creating a center image that depicts it.** Design a simple, unambiguous image that’s clear and recognizable at every size. The center image measures half the size of the overall document icon canvas. For example, to create a center image for a 32x32 px document icon, use an image canvas that measures 16x16 px. You can provide center images in the following sizes:
+
+  * 256x256 px @1x, 512x512 px @2x
+
+  * 128x128 px @1x, 256x256 px @2x
+
+  * 32x32 px @1x, 64x64 px @2x
+
+  * 16x16 px @1x, 32x32 px @2x
+
+
+
+
+**Define a margin that measures about 10% of the image canvas and keep most of the image within it.** Although parts of the image can extend into this margin for optical alignment, it’s best when the image occupies about 80% of the image canvas. For example, most of the center image in a 256x256 px canvas would fit in an area that measures 205x205 px.
+
+![Diagram of the solid pink heart shape within blue margins that measure 10 percent of the canvas width.](https://docs-assets.developer.apple.com/published/7cc19b2ae1e99d26ba69e1351683ede1/doc-icon-parts-margins%402x.png)
+
+**Specify a succinct term if it helps people understand your document type.** By default, the system displays a document’s extension at the bottom edge of the document icon, but if the extension is unfamiliar you can supply a more descriptive term. For example, the document icon for a SceneKit scene file uses the term _scene_ instead of the file extension _scn_. The system automatically scales the extension text to fit in the document icon, so be sure to use a term that’s short enough to be legible at small sizes. By default, the system capitalizes every letter in the text.
+
+![Image of a SceneKit scene document icon.](https://docs-assets.developer.apple.com/published/3b4bb7de9edb5870d3a162aae8153163/doc-icon-custom-extension%402x.png)
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/icons#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/icons#Related)
+
+[App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons)
+
+[SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/icons#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/7/597D59A1-F123-4B08-BEE1-6D79A4C22268/1914_wide_250x141_1x.jpg) Designing Glyphs ](https://developer.apple.com/videos/play/wwdc2017/823)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/icons#Change-log)
+
+Date| Changes  
+---|---  
+June 9, 2025| Added a table of SF Symbols that represent common actions.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/skills/hig-foundations/references/images.md

@@ -0,0 +1,176 @@
+---
+title: "Images | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/images
+
+# Images
+
+To make sure your artwork looks great on all devices you support, learn how the system displays content and how to deliver art at the appropriate scale factors.
+
+![A sketch of a photo, suggesting imagery. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/b0a68ac859ddb098858e92609997d307/foundations-images-intro%402x.png)
+
+## [Resolution](https://developer.apple.com/design/human-interface-guidelines/images#Resolution)
+
+Different devices can display images at different resolutions. For example, a 2D device displays images according to the resolution of its screen.
+
+A _point_ is an abstract unit of measurement that helps visual content remain consistent regardless of how it’s displayed. In 2D platforms, a point maps to a number of pixels that can vary according to the resolution of the display; in visionOS, a point is an angular value that allows visual content to scale according to its distance from the viewer.
+
+When creating bitmap images, you specify a _scale factor_ which determines the resolution of an image. You can visualize scale factor by considering the density of pixels per point in 2D displays of various resolutions. For example, a scale factor of 1 (also called @1x) describes a 1:1 pixel density, where one pixel is equal to one point. High-resolution 2D displays have higher pixel densities, such as 2:1 or 3:1. A 2:1 density (called @2x) has a scale factor of 2, and a 3:1 density (called @3x) has a scale factor of 3. Because of higher pixel densities, high-resolution displays demand images with more pixels.
+
+![Image of a circle that's in standard resolution at scale factor of @1x, and is 10 by 10 pixels.](https://docs-assets.developer.apple.com/published/a9b04545f30aff45ca503e263c02d464/image-resolution-1x%402x.png)1x (10x10 px)
+
+![Image of a circle that's in high resolution at a scale factor of @2x, and is 20 by 20 pixels.](https://docs-assets.developer.apple.com/published/cf203acc0ee6299833fb2e5b5c4a7348/image-resolution-2x%402x.png)2x (20x20 px)
+
+![Image of a circle that's in high resolution at a scale factor of @3x, and is 30 by 30 pixels.](https://docs-assets.developer.apple.com/published/0de9ee5144fc2278682eb211ac8f571d/image-resolution-3x%402x.png)3x (30x30 px)
+
+**Provide high-resolution assets for all bitmap images in your app, for every device you support.** As you add each image to your project’s asset catalog, identify its scale factor by appending “@1x,” “@2x,” or “@3x” to its filename. Use the following values for guidance; for additional scale factors, see [Layout](https://developer.apple.com/design/human-interface-guidelines/layout).
+
+Platform| Scale factors  
+---|---  
+iPadOS, watchOS| @2x  
+iOS| @2x and @3x  
+visionOS| @2x or higher (see [visionOS](https://developer.apple.com/design/human-interface-guidelines/images#visionOS))  
+macOS, tvOS| @1x and @2x  
+  
+**In general, design images at the lowest resolution and scale them up to create high-resolution assets.** When you use resizable vectorized shapes, you might want to position control points at whole values so that they’re cleanly aligned at 1x. This positioning allows the points to remain cleanly aligned to the raster grid at higher resolutions, because 2x and 3x are multiples of 1x.
+
+## [Formats](https://developer.apple.com/design/human-interface-guidelines/images#Formats)
+
+As you create different types of images, consider the following recommendations.
+
+Image type| Format  
+---|---  
+Bitmap or raster work| De-interlaced PNG files  
+PNG graphics that don’t require full 24-bit color| An 8-bit color palette  
+Photos| JPEG files, optimized as necessary, or HEIC files  
+Stereo or spatial photos| Stereo HEIC  
+Flat icons, interface icons, and other flat artwork that requires high-resolution scaling| PDF or SVG files  
+  
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/images#Best-practices)
+
+**Include a color profile with each image.** Color profiles help ensure that your app’s colors appear as intended on different displays. For guidance, see [Color management](https://developer.apple.com/design/human-interface-guidelines/color#Color-management).
+
+**Always test images on a range of actual devices.** An image that looks great at design time may appear pixelated, stretched, or compressed when viewed on various devices.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/images#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or macOS._
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/images#tvOS)
+
+Layered images are at the heart of the Apple TV user experience. The system combines layered images, transparency, scaling, and motion to produce a sense of realism and vigor that evokes a personal connection as people interact with onscreen content.
+
+#### [Parallax effect](https://developer.apple.com/design/human-interface-guidelines/images#Parallax-effect)
+
+ _Parallax_ is a subtle visual effect the system uses to convey depth and dynamism when an element is in focus. As an element comes into focus, the system elevates it to the foreground, gently swaying it while applying illumination that makes the element’s surface appear to shine. After a period of inactivity, out-of-focus content dims and the focused element expands.
+
+Layered images are required to support the parallax effect.
+
+Video with custom controls. 
+
+Content description: An animation of a tvOS app icon moving to show the parallax effect. 
+
+Play 
+
+#### [Layered images](https://developer.apple.com/design/human-interface-guidelines/images#Layered-images)
+
+A _layered image_ consists of two to five distinct layers that come together to form a single image. The separation between layers, along with use of transparency, creates a feeling of depth. As someone interacts with an image, layers closer to the surface elevate and scale, overlapping lower layers farther back and producing a 3D effect.
+
+Important
+
+Your tvOS [app icon](https://developer.apple.com/design/human-interface-guidelines/app-icons#tvOS) must use a layered image. For other focusable images in your app, including [Top Shelf](https://developer.apple.com/design/human-interface-guidelines/top-shelf) images, layered images are strongly encouraged, but optional.
+
+You can embed layered images in your app or retrieve them from a content server at runtime. For guidance on adding layered images to your app, see the [Parallax Previewer User Guide](https://help.apple.com/itc/parallaxpreviewer/).
+
+Developer note
+
+If your app retrieves layered images from a content server at runtime, you must provide runtime layered images (`.lcr`). You can generate them from LSR files or Photoshop files using the `layerutil` command-line tool that Xcode provides. Runtime layered images are intended to be downloaded — don’t embed them in your app.
+
+**Use standard interface elements to display layered images.** If you use standard views and system-provided focus APIs — such as [`FocusState`](https://developer.apple.com/documentation/SwiftUI/FocusState) — layered images automatically get the parallax treatment when people bring them into focus.
+
+**Identify logical foreground, middle, and background elements.** In foreground layers, display prominent elements like a character in a game, or text on an album cover or movie poster. Middle layers are perfect for secondary content and effects like shadows. Background layers are opaque backdrops that showcase the foreground and middle layers without upstaging them.
+
+**Generally, keep text in the foreground.** Unless you want to obscure text, bring it to the foreground layer for clarity.
+
+**Keep the background layer opaque.** Using varying levels of opacity to let content shine through higher layers is fine, but your background layer must be opaque — you’ll get an error if it’s not. An opaque background layer ensures your artwork looks great with parallax, drop shadows, and system backgrounds.
+
+**Keep layering simple and subtle.** Parallax is designed to be almost unnoticeable. Excessive 3D effects can appear unrealistic and jarring. Keep depth simple to bring your content to life and add delight.
+
+**Leave a safe zone around the foreground layers of your image.** When focused, content on some layers may be cropped as the layered image scales and moves. To ensure that essential content is always visible, keep it within a safe zone. For guidance, see [App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons).
+
+**Always preview layered images.** To ensure your layered images look great on Apple TV, preview them throughout your design process using Xcode, the Parallax Previewer app for macOS, or the Parallax Exporter plug-in for Adobe Photoshop. Pay special attention as scaling and clipping occur, and readjust your images as needed to keep important content safe. After your layered images are final, preview them on an actual TV for the most accurate representation of what people will see. To download Parallax Previewer and Parallax Exporter, see [Resources](https://developer.apple.com/design/resources/#parallax-previewer).
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/images#visionOS)
+
+In visionOS, people can view images at a much larger range of sizes than in any other platform, and the system dynamically scales the image resolution to match the current size. Because you can position images at specific angles within someone’s surroundings, image pixels may not line up 1:1 with screen pixels.
+
+**Create a layered app icon.** App icons in visionOS are composed of two to three layers that provide the appearance of depth by moving at subtly different rates when the icon is in focus. For guidance, see [Layer design](https://developer.apple.com/design/human-interface-guidelines/app-icons#Layer-design).
+
+**Prefer vector-based art for 2D images.** Avoid bitmap content because it might not look good when the system scales it up. If you use Core Animation layers, see [Drawing sharp layer-based content in visionOS](https://developer.apple.com/documentation/visionOS/drawing-sharp-layer-based-content) for developer guidance.
+
+**If you need to use rasterized images, balance quality with performance as you choose a resolution.** Although a @2x image looks fine at common viewing distances, its fixed resolution means that the system doesn’t dynamically scale it and it might not look sharp from close up. To help a rasterized image look sharp when people view it from a wide range of distances, you can use a higher resolution, but each increase in resolution results in a larger file size and may impact your app’s runtime performance, especially for resolutions over @6x. If you use images that have resolutions higher than @2x, be sure to also apply high-quality image filtering to help balance quality and performance (for developer guidance, see [`filters`](https://developer.apple.com/documentation/QuartzCore/CALayer/filters)).
+
+#### [Spatial photos and spatial scenes](https://developer.apple.com/design/human-interface-guidelines/images#Spatial-photos-and-spatial-scenes)
+
+In addition to 2D and stereoscopic images, visionOS apps and games can use RealityKit to display spatial photos and spatial scenes. A _spatial photo_ is a stereoscopic photo with additional spatial metadata, as captured on iPhone 15 Pro or later, Apple Vision Pro, or other compatible camera. A _spatial scene_ is a 3D image generated from a 2D image to add a parallax effect that responds to head movement. For developer guidance, see [`ImagePresentationComponent`](https://developer.apple.com/documentation/RealityKit/ImagePresentationComponent).
+
+**Make sure spatial photos render correctly in your app.** Use the stereo High-Efficiency Image Codec (HEIC) format to display a spatial photo in your app. When you add spatial metadata to a stereo HEIC, visionOS recognizes the photo as spatial and includes visual treatments that help minimize common causes of stereo-viewing discomfort.
+
+**Prefer the feathered glass background effect to display text over spatial photos.** If you need to place text over a spatial photo in your app or game, use the feathered glass background effect. The effect adds contrast to make the text readable, and it blurs out detail to help reduce visual discomfort when people view text over spatial photos. For developer guidance, see [`GlassBackgroundEffect`](https://developer.apple.com/documentation/SwiftUI/GlassBackgroundEffect).
+
+**Take visual comfort into consideration when you make spatial photos from existing 2D content.** When adjusting the spatial metadata of a photo for your app or game, consider how you want people to view your content. Metadata like disparity adjustment can alter how people perceive the 3D scene, and can cause visual discomfort from certain viewing positions. For developer guidance, see [Creating spatial photos and videos with spatial metadata](https://developer.apple.com/documentation/ImageIO/Creating-spatial-photos-and-videos-with-spatial-metadata).
+
+**Display spatial photos and spatial scenes in standalone views.** Avoid displaying spatial photos inline with other content, as this can cause visual discomfort. Instead, showcase spatial photos or spatial scenes in a separate view, like a sheet or window. If you must display stereoscopic images inline, provide generous spacing between the image and any inline content to help people’s eyes adjust to the depth changes.
+
+**Use spatial scenes in your app for specific moments.** Each spatial scene can take up to several seconds to generate from an existing image. Design experiences with this limitation in mind. For instance, the Photos app offers an explicit action to create a spatial scene while immersed in a single photo. Avoid displaying too many spatial scenes at once. Instead, use scroll views, pagination, or explicit actions to move to new photos and keep the visual information hierarchy simple.
+
+**When displaying immersively, prefer minimal UI.** For example, the Spatial Gallery app displays a single piece of content with a small caption and a single Back button, relying on swipe gestures to navigate between items.
+
+**Prefer displaying larger spatial scenes that you center in someone’s field of view.** When people view a spatial scene, they may move their head laterally to view the parallax effect. Smaller spatial scenes provide less of a parallax effect and may not be as impactful to viewers.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/images#watchOS)
+
+**In general, avoid transparency to keep image files small.** If you always composite an image on the same solid background color, it’s more efficient to include the background in the image. However, transparency is necessary in complication images, menu icons, and other interface icons that serve as template images, because the system uses it to determine where to apply color.
+
+**Use autoscaling PDFs to let you provide a single asset for all screen sizes.** Design your image for the 40mm and 42mm screens at 2x. When you load the PDF, WatchKit automatically scales the image based on the device’s screen size, using the values shown below:
+
+Screen size| Image scale  
+---|---  
+38mm| 90%  
+40mm| 100%  
+41mm| 106%  
+42mm| 100%  
+44mm| 110%  
+45mm| 119%  
+49mm| 119%  
+  
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/images#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/images#Related)
+
+[Apple Design Resources](https://developer.apple.com/design/resources/)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/images#Developer-documentation)
+
+[Drawing sharp layer-based content in visionOS](https://developer.apple.com/documentation/visionOS/drawing-sharp-layer-based-content) — visionOS
+
+[Images](https://developer.apple.com/documentation/SwiftUI/Images) — SwiftUI
+
+[`UIImageView`](https://developer.apple.com/documentation/UIKit/UIImageView) — UIKit
+
+[`NSImageView`](https://developer.apple.com/documentation/AppKit/NSImageView) — AppKit
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/images#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/8226C70F-64DC-4FF1-9956-2DC0751A2143/8241_wide_250x141_1x.jpg) Support HDR images in your app ](https://developer.apple.com/videos/play/wwdc2023/10181)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/7/09438FDD-3E8B-42A3-A364-78E1A7F2CE6B/1915_wide_250x141_1x.jpg) Get Started with Display P3 ](https://developer.apple.com/videos/play/wwdc2017/821)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/images#Change-log)
+
+Date| Changes  
+---|---  
+December 16, 2025| Added guidance for spatial photos and spatial scenes in visionOS.  
+December 5, 2023| Clarified guidance on choosing a resolution for a rasterized image in a visionOS app.  
+June 21, 2023| Updated to include guidance for visionOS.  
+September 14, 2022| Added specifications for Apple Watch Ultra.  
+