{ "metadata": { "source": "Apple Human Interface Guidelines", "source_url": "https://developer.apple.com/design/human-interface-guidelines/", "generated_at": "2026-03-24T10:09:01.952605+00:00", "article_count": 134, "format_version": "1.0", "purpose": "Agent-readable reference for designing Swift/SwiftUI applications following Apple HIG", "category": "foundations" }, "name": "Foundations", "articles": [ { "title": "Accessibility", "url": "https://developer.apple.com/design/human-interface-guidelines/accessibility", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When you design for accessibility, you reach a larger audience and create a more inclusive experience. An accessible interface allows people to experience your app or game regardless of their capabilities or how they use their devices. Accessibility makes information and interactions available to everyone. An accessible interface is:" }, { "type": "list", "items": [ "Intuitive. Your interface uses familiar and consistent interactions that make tasks straightforward to perform.", "Perceivable. Your interface doesn’t rely on any single method to convey information. People can access and interact with your content, whether they use sight, hearing, speech, or touch.", "Adaptable. Your interface adapts to how people want to use their device, whether by supporting system accessibility features or letting people personalize settings." ] }, { "type": "paragraph", "text": "As you design your app, audit the accessibility of your interface. Use Accessibility Inspector to highlight accessibility issues with your interface and to understand how your app represents itself to people using system accessibility features. You can also communicate how accessible your app is on the App Store using Accessibility Nutrition Labels. To learn more about how to evaluate and indicate accessibility feature support, see Accessibility Nutrition Labels in App Store Connect help." } ] }, { "heading": "Vision", "level": 2, "content": [ { "type": "paragraph", "text": "The people who use your interface may be blind, color blind, or have low vision or light sensitivity. They may also be in situations where lighting conditions and screen brightness affect their ability to interact with your interface." }, { "type": "paragraph", "text": "Support larger text sizes. Make sure people can adjust the size of your text or icons to make them more legible, visible, and comfortable to read. Ideally, give people the option to enlarge text by at least 200 percent (or 140 percent in watchOS apps). Your interface can support font size enlargement either through custom UI, or by adopting Dynamic Type. Dynamic Type is a systemwide setting that lets people adjust the size of text for comfort and legibility. For more guidance, see Supporting Dynamic Type." }, { "type": "paragraph", "text": "Use recommended defaults for custom type sizes. Each platform has different default and minimum sizes for system-defined type styles to promote readability. If you’re using custom type styles, follow the recommended defaults." }, { "type": "table", "rows": [ [ "Platform", "Default size", "Minimum size" ], [ "iOS, iPadOS", "17 pt", "11 pt" ], [ "macOS", "13 pt", "10 pt" ], [ "tvOS", "29 pt", "23 pt" ], [ "visionOS", "17 pt", "12 pt" ], [ "watchOS", "16 pt", "12 pt" ] ] }, { "type": "paragraph", "text": "Bear in mind that font weight can also impact how easy text is to read. If you’re using a custom font with a thin weight, aim for larger than the recommended sizes to increase legibility. For more guidance, see Typography." }, { "type": "paragraph", "text": "Thicker weights are easier to read for smaller font sizes." }, { "type": "paragraph", "text": "Consider increasing the font size when using a thin weight." }, { "type": "paragraph", "text": "Strive to meet color contrast minimum standards. To ensure all information in your app is legible, it’s important that there’s enough contrast between foreground text and icons and background colors. Two popular standards of measure for color contrast are the Web Content Accessibility Guidelines (WCAG) and the Accessible Perceptual Contrast Algorithm (APCA). Use standard contrast calculators to ensure your UI meets acceptable levels. Accessibility Inspector uses the following values from WCAG Level AA as guidance in determining whether your app’s colors have an acceptable contrast." }, { "type": "table", "rows": [ [ "Text size", "Text weight", "Minimum contrast ratio" ], [ "Up to 17 pts", "All", "4.5:1" ], [ "18 pts", "All", "3:1" ], [ "All", "Bold", "3:1" ] ] }, { "type": "paragraph", "text": "If your app doesn’t provide this minimum contrast by default, ensure it at least provides a higher contrast color scheme when the system setting Increase Contrast is turned on. If your app supports Dark Mode, make sure to check the minimum contrast in both light and dark appearances." }, { "type": "paragraph", "text": "A button with insufficient color contrast" }, { "type": "paragraph", "text": "A button with sufficient color contrast" }, { "type": "paragraph", "text": "Prefer system-defined colors. These colors have their own accessible variants that automatically adapt when people adjust their color preferences, such as enabling Increase Contrast or toggling between the light and dark appearances. For guidance, see Color." }, { "type": "paragraph", "text": "The systemRed default color in iOS" }, { "type": "paragraph", "text": "The systemRed accessible color in iOS" }, { "type": "paragraph", "text": "Convey information with more than color alone. Some people have trouble differentiating between certain colors and shades. For example, people who are color blind may have particular difficulty with pairings such as red-green and blue-orange. Offer visual indicators, like distinct shapes or icons, in addition to color to help people perceive differences in function and changes in state. Consider allowing people to customize color schemes such as chart colors or game characters so they can personalize your interface in a way that’s comfortable for them." }, { "type": "paragraph", "text": "For someone with red-green color blindness, these indicators might appear the same." }, { "type": "paragraph", "text": "Both visual indicators and color help differentiate between indicators." }, { "type": "paragraph", "text": "Describe your app’s interface and content for VoiceOver. VoiceOver is a screen reader that lets people experience your app’s interface without needing to see the screen. For more guidance, see VoiceOver." } ] }, { "heading": "Hearing", "level": 2, "content": [ { "type": "paragraph", "text": "The people who use your interface may be deaf or hard of hearing. They may also be in noisy or public environments." }, { "type": "paragraph", "text": "Support text-based ways to enjoy audio and video. It’s important that dialogue and crucial information about your app or game isn’t communicated through audio alone. Depending on the context, give people different text-based ways to experience their media, and allow people to customize the visual presentation of that text:" }, { "type": "list", "items": [ "Captions give people the textual equivalent of audible information in video or audio-only content. Captions are great for scenarios like game cutscenes and video clips where text synchronizes live with the media.", "Subtitles allow people to read live onscreen dialogue in their preferred language. Subtitles are great for TV shows and movies.", "Audio descriptions are interspersed between natural pauses in the main audio of a video and supply spoken narration of important information that’s presented only visually.", "Transcripts provide a complete textual description of a video, covering both audible and visual information. Transcripts are great for longer-form media like podcasts and audiobooks where people may want to review content as a whole or highlight the transcript as media is playing." ] }, { "type": "paragraph", "text": "For developer guidance, see Selecting subtitles and alternative audio tracks." }, { "type": "paragraph", "text": "Use haptics in addition to audio cues. If your interface conveys information through audio cues — such as a success chime, error sound, or game feedback — consider pairing that sound with matching haptics for people who can’t perceive the audio or have their audio turned off. In iOS and iPadOS, you can also use Music Haptics and Audio graphs to let people experience music and infographics through vibration and texture. For guidance, see Playing haptics." }, { "type": "paragraph", "text": "Augment audio cues with visual cues. This is especially important for games and spatial apps where important content might be taking place off screen. When using audio to guide people towards a specific action, also add in visual indicators that point to where you want people to interact." } ] }, { "heading": "Mobility", "level": 2, "content": [ { "type": "paragraph", "text": "Ensure your interface offers a comfortable experience for people with limited dexterity or mobility." }, { "type": "paragraph", "text": "Offer sufficiently sized controls. Controls that are too small are hard for many people to interact with and select. Strive to meet the recommended minimum control size for each platform to ensure controls and menus are comfortable for all when tapping and clicking." }, { "type": "table", "rows": [ [ "Platform", "Default control size", "Minimum control size" ], [ "iOS, iPadOS", "44x44 pt", "28x28 pt" ], [ "macOS", "28x28 pt", "20x20 pt" ], [ "tvOS", "66x66 pt", "56x56 pt" ], [ "visionOS", "60x60 pt", "28x28 pt" ], [ "watchOS", "44x44 pt", "28x28 pt" ] ] }, { "type": "paragraph", "text": "Consider spacing between controls as important as size. Include enough padding between elements to reduce the chance that someone taps the wrong control. In general, it works well to add about 12 points of padding around elements that include a bezel. For elements without a bezel, about 24 points of padding works well around the element’s visible edges." }, { "type": "paragraph", "text": "Elements with insufficient padding" }, { "type": "paragraph", "text": "Elements with sufficient padding" }, { "type": "paragraph", "text": "Support simple gestures for common interactions. For many people, with or without disabilities, complex gestures can be challenging. For interactions people do frequently in your app or game, use the simplest gesture possible — avoid custom multifinger and multihand gestures — so repetitive actions are both comfortable and easy to remember." }, { "type": "paragraph", "text": "Offer alternatives to gestures. Make sure your UI’s core functionality is accessible through more than one type of physical interaction. Gestures can be less comfortable for people who have limited dexterity, so offer onscreen ways to achieve the same outcome. For example, if you use a swipe gesture to dismiss a view, also make a button available so people can tap or use an assistive device." }, { "type": "paragraph", "text": "Edit and tap to delete" }, { "type": "paragraph", "text": "Swipe to delete" }, { "type": "paragraph", "text": "Let people use Voice Control to give guidance and enter information verbally. With Voice Control, people can interact with their devices entirely by speaking commands. They can perform gestures, interact with screen elements, dictate and edit text, and more. To ensure a smooth experience, label interface elements appropriately. For developer guidance, see Voice Control." }, { "type": "paragraph", "text": "Integrate with Siri and Shortcuts to let people perform tasks using voice alone. When your app supports Siri and Shortcuts, people can automate the important and repetitive tasks they perform regularly. They can initiate these tasks from Siri, the Action button on their iPhone or Apple Watch, and shortcuts on their Home Screen or in Control Center. For guidance, see Siri." }, { "type": "paragraph", "text": "Support mobility-related assistive technologies. Features like VoiceOver, AssistiveTouch, Full Keyboard Access, Pointer Control, and Switch Control offer alternative ways for people with low mobility to interact with their devices. Conduct testing and verify that your app or game supports these technologies, and that your interface elements are appropriately labeled to ensure a great experience. For more information, see Performing accessibility testing for your app." } ] }, { "heading": "Speech", "level": 2, "content": [ { "type": "paragraph", "text": "Apple’s accessibility features help people with speech disabilities and people who prefer text-based interactions to communicate effectively using their devices." }, { "type": "paragraph", "text": "Let people use the keyboard alone to navigate and interact with your app. People can turn on Full Keyboard Access to navigate apps using their physical keyboard. The system also defines accessibility keyboard shortcuts and a wide range of other keyboard shortcuts that many people use all the time. Avoid overriding system-defined keyboard shortcuts and evaluate your app to ensure it works well with Full Keyboard Access. For additional guidance, see Keyboards. For developer guidance, see Support Full Keyboard Access in your iOS app." }, { "type": "paragraph", "text": "Support Switch Control. Switch Control is an assistive technology that lets people control their devices through separate hardware, game controllers, or sounds such as a click or a pop. People can perform actions like selecting, tapping, typing, and drawing when your app or game supports the ability to navigate using Switch Control. For developer guidance, see Switch Control." } ] }, { "heading": "Cognitive", "level": 2, "content": [ { "type": "paragraph", "text": "When you minimize complexity in your app or game, all people benefit." }, { "type": "paragraph", "text": "Keep actions simple and intuitive. Ensure that people can navigate your interface using easy-to-remember and consistent interactions. Prefer system gestures and behaviors people are already familiar with over creating custom gestures people must learn and retain." }, { "type": "paragraph", "text": "Minimize use of time-boxed interface elements. Views and controls that auto-dismiss on a timer can be problematic for people who need longer to process information, and for people who use assistive technologies that require more time to traverse the interface. Prefer dismissing views with an explicit action." }, { "type": "paragraph", "text": "Consider offering difficulty accommodations in games. Everyone has their own way of playing and enjoying games. To support a variety of cognitive abilities, consider adding the ability to customize the difficulty level of your game, such as offering options for people to reduce the criteria for successfully completing a level, adjust reaction time, or enable control assistance." }, { "type": "paragraph", "text": "Let people control audio and video playback. Avoid autoplaying audio and video content without also providing controls to start and stop it. Make sure these controls are discoverable and easy to act upon, and consider global settings that let people opt out of auto-playing all audio and video. For developer guidance, see Animated images and isVideoAutoplayEnabled." }, { "type": "paragraph", "text": "Allow people to opt out of flashing lights in video playback. People might want to avoid bright, frequent flashes of light in the media they consume. A Dim Flashing Lights setting allows the system to calculate, mitigate, and inform people about flashing lights in a piece of media. If your app supports video playback, ensure that it responds appropriately to the Dim Flashing Lights setting. For developer guidance, see Flashing lights." }, { "type": "paragraph", "text": "Be cautious with fast-moving and blinking animations. When you use these effects in excess, it can be distracting, cause dizziness, and in some cases even result in epileptic episodes. People who are prone to these effects can turn on the Reduce Motion accessibility setting. When this setting is active, ensure your app or game responds by reducing automatic and repetitive animations, including zooming, scaling, and peripheral motion. Other best practices for reducing motion include:" }, { "type": "list", "items": [ "Tightening animation springs to reduce bounce effects", "Tracking animations directly with people’s gestures", "Avoiding animating depth changes in z-axis layers", "Replacing transitions in x-, y-, and z-axes with fades to avoid motion", "Avoiding animating into and out of blurs" ] }, { "type": "paragraph", "text": "Optimize your app’s UI for Assistive Access. Assistive Access is an accessibility feature in iOS and iPadOS that allows people with cognitive disabilities to use a streamlined version of your app. Assistive Access sets a default layout and control presentation for apps that reduces cognitive load, such as the following layout of the Camera app." }, { "type": "paragraph", "text": "To optimize your app for this mode, use the following guidelines when Assistive Access is turned on:" }, { "type": "list", "items": [ "Identify the core functionality of your app and consider removing noncritical workflows and UI elements.", "Break up multistep workflows so people can focus on a single interaction per screen.", "Always ask for confirmation twice whenever people perform an action that’s difficult to recover from, such a deleting a file." ] }, { "type": "paragraph", "text": "For developer guidance, see Assistive Access." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or watchOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "visionOS offers a variety of accessibility features people can use to interact with their surroundings in ways that are comfortable and work best for them, including head and hand Pointer Control, and a Zoom feature." }, { "type": "paragraph", "text": "Prioritize comfort. The immersive nature of visionOS means that interfaces, animations, and interactions have a greater chance of causing motion sickness, and visual and ergonomic discomfort for people. To ensure the most comfortable experience, consider these tips:" }, { "type": "list", "items": [ "Keep interface elements within a person’s field of view. Prefer horizontal layouts to vertical ones that might cause neck strain, and avoid demanding the viewer’s attention in different locations in quick succession.", "Reduce the speed and intensity of animated objects, particularly in someone’s peripheral vision.", "Be gentle with camera and video motion, and avoid situations where someone may feel like the world around them is moving without their control.", "Avoid anchoring content to the wearer’s head, which may make them feel stuck and confined, and also prevent them from using assistive technologies like Pointer Control.", "Minimize the need for large and repetitive gestures, as these can become tiresome and may be difficult depending on a person’s surroundings." ] }, { "type": "paragraph", "text": "For additional guidance, see Create accessible spatial experiences and Design considerations for vision and motion." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Inclusion" }, { "type": "paragraph", "text": "Typography" }, { "type": "paragraph", "text": "VoiceOver" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Building accessible apps" }, { "type": "paragraph", "text": "Accessibility framework" }, { "type": "paragraph", "text": "Overview of Accessibility Nutrition Labels" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added guidance and links for Assistive Access, Switch Control, and Accessibility Nutrition Labels." ], [ "March 7, 2025", "Expanded and refined all guidance. Moved Dynamic Type guidance to the Typography page, and moved VoiceOver guidance to a new VoiceOver page." ], [ "June 10, 2024", "Added a link to Apple’s Unity plug-ins for supporting Dynamic Type." ], [ "December 5, 2023", "Updated visionOS Zoom lens artwork." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Vision", "url": "/design/human-interface-guidelines/accessibility#Vision" }, { "title": "Supporting Dynamic Type", "url": "/design/human-interface-guidelines/typography#Supporting-Dynamic-Type" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Dark Mode", "url": "/design/human-interface-guidelines/dark-mode" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "VoiceOver", "url": "/design/human-interface-guidelines/voiceover" }, { "title": "Hearing", "url": "/design/human-interface-guidelines/accessibility#Hearing" }, { "title": "Playing haptics", "url": "/design/human-interface-guidelines/playing-haptics" }, { "title": "Mobility", "url": "/design/human-interface-guidelines/accessibility#Mobility" }, { "title": "Siri", "url": "/design/human-interface-guidelines/siri" }, { "title": "Speech", "url": "/design/human-interface-guidelines/accessibility#Speech" }, { "title": "Keyboards", "url": "/design/human-interface-guidelines/keyboards" }, { "title": "Cognitive", "url": "/design/human-interface-guidelines/accessibility#Cognitive" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/accessibility#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/accessibility#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/accessibility#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/accessibility#Related" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/accessibility#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/accessibility#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/accessibility#Change-log" } ], "image_count": 0 }, { "title": "App icons", "url": "https://developer.apple.com/design/human-interface-guidelines/app-icons", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Your app icon is a crucial aspect of your app’s or game’s branding and user experience. It appears on the Home Screen and in key locations throughout the system, including search results, notifications, system settings, and share sheets. A well-designed app icon conveys your app’s or game’s identity clearly and consistently across all Apple platforms." } ] }, { "heading": "Layer design", "level": 2, "content": [ { "type": "paragraph", "text": "Although you can provide a flattened image for your icon, layers give you the most control over how your icon design is represented. A layered app icon comes together to produce a sense of depth and vitality. On each platform, the system applies visual effects that respond to the environment and people’s interactions." }, { "type": "paragraph", "text": "iOS, iPadOS, macOS, and watchOS app icons include a background layer and one or more foreground layers that coalesce to create dimensionality. These icons take on Liquid Glass attributes like specular highlights, frostiness, and translucency, which respond to changes in lighting and, in iOS and iPadOS, device movement." }, { "type": "image", "alt": "", "caption": "iOS app icon" }, { "type": "paragraph", "text": "tvOS app icons use between two and five layers to create a sense of dynamism as people bring them into focus. When focused, the app icon elevates to the foreground in response to someone’s finger movement on their remote, and gently sways while the surface illuminates. The separation between layers and the use of transparency produce a feeling of depth during the parallax effect." }, { "type": "image", "alt": "", "caption": "tvOS app icon" }, { "type": "paragraph", "text": "A visionOS app icon includes a background layer and one or two layers on top, producing a three-dimensional object that subtly expands when people view it. The system enhances the icon’s visual dimensionality by adding shadows that convey a sense of depth between layers and by using the alpha channel of the upper layers to create an embossed appearance." }, { "type": "image", "alt": "", "caption": "visionOS app icon" }, { "type": "paragraph", "text": "You use your favorite design tool to craft the individual foreground layers of your app icon. For iOS, iPadOS, macOS, and watchOS icons, you then import your icon layers into Icon Composer, a design tool included with Xcode and available from the Apple Developer website. In Icon Composer, you define the background layer for your icon, adjust your foreground layer placement, apply visual effects like transparency, define default, dark, clear, and tinted appearance variants, and export your icon for use in Xcode. For additional guidance, see Creating your app icon using Icon Composer." }, { "type": "paragraph", "text": "Icon Composer" }, { "type": "paragraph", "text": "For tvOS and visionOS app icons, you add your icon layers directly to an image stack in Xcode to form your complete icon. For developer guidance, see Configuring your app icon using an asset catalog." }, { "type": "paragraph", "text": "Prefer clearly defined edges in foreground layers. To ensure system-drawn highlights and shadows look best, avoid soft and feathered edges on foreground layer shapes." }, { "type": "paragraph", "text": "Vary opacity in foreground layers to increase the sense of depth and liveliness. For example, the Photos icon separates its centerpiece into multiple layers that contain translucent pieces, bringing greater dynamism to the design. Importing fully opaque layers and adjusting transparency in Icon Composer lets you preview and make adjustments to your design based on how transparency and system effects impact one another." }, { "type": "paragraph", "text": "Design a background that both stands out and emphasizes foreground content. Subtle top-to-bottom, light-to-dark gradients tend to respond well to system lighting effects. Icon Composer supports solid colors and gradients for background layers, making it unnecessary to import custom background images in most cases. If you do import a background layer, make sure it’s full-bleed and opaque." }, { "type": "paragraph", "text": "Prefer vector graphics when bringing layers into Icon Composer. Unlike raster images, vector graphics (such as SVG or PDF) scale gracefully and appear crisp at any size. Outline artwork and convert text to outline in your design. For mesh gradients and raster artwork, prefer PNG format because it’s a lossless image format." } ] }, { "heading": "Icon shape", "level": 2, "content": [ { "type": "paragraph", "text": "An app icon’s shape varies based on a platform’s visual language. In iOS, iPadOS, and macOS, icons are square, and the system applies masking to produce rounded corners that precisely match the curvature of other rounded interface elements throughout the system and the bezel of the physical device itself. In tvOS, icons are rectangular, also with concentric edges. In visionOS and watchOS, icons are square and the system applies circular masking." }, { "type": "paragraph", "text": "Produce appropriately shaped, unmasked layers. The system masks all layer edges to produce an icon’s final shape. For iOS, iPadOS, and macOS icons, provide square layers so the system can apply rounded corners. For visionOS and watchOS, provide square layers so the system can create the circular icon shape. For tvOS, provide rectangular layers so the system can apply rounded corners. Providing layers with pre-defined masking negatively impacts specular highlight effects and makes edges look jagged." }, { "type": "paragraph", "text": "Keep primary content centered to avoid truncation when the system adjusts corners or applies masking. Pay particular attention to centering content in visionOS and watchOS icons. To help with icon placement, use the grids in the app icon production templates, which you can find in Apple Design Resources." } ] }, { "heading": "Design", "level": 2, "content": [ { "type": "paragraph", "text": "Embrace simplicity in your icon design. Simple icons tend to be easiest for people to understand and recognize. An icon with fine visual features might look busy when rendered with system-provided shadows and highlights, and details may be hard to discern at smaller sizes. Find a concept or element that captures the essence of your app or game, make it the core idea of your icon, and express it in a simple, unique way with a minimal number of shapes. Prefer a simple background, such as a solid color or gradient, that puts the emphasis on your primary design — you don’t need to fill the entire icon canvas with content." }, { "type": "paragraph", "text": "The Podcasts app icon" }, { "type": "paragraph", "text": "The Home app icon" }, { "type": "paragraph", "text": "Provide a visually consistent icon design across all the platforms your app supports. A consistent design helps people quickly find your app wherever it appears and prevents people from mistaking your app for multiple apps." }, { "type": "paragraph", "text": "Consider basing your icon design around filled, overlapping shapes. Overlapping solid shapes in the foreground, particularly when paired with transparency and blurring, can give an icon a sense of depth." }, { "type": "paragraph", "text": "Include text only when it’s essential to your experience or brand. Text in icons doesn’t support accessibility or localization, is often too small to read easily, and can make an icon appear cluttered. In some contexts, your app name already appears nearby, making it redundant to display the name within the icon itself. Although displaying a mnemonic like the first letter of your app’s name can help people recognize your app or game, avoid including nonessential words that tell people what to do with it — like “Watch” or “Play” — or context-specific terms like “New” or “For visionOS.” If you include text in a tvOS app icon, make sure it’s above other layers so it’s not cropped by the parallax effect." }, { "type": "paragraph", "text": "Prefer illustrations to photos and avoid replicating UI components. Photos are full of details that don’t work well when displayed in different appearances, viewed at small sizes, or split into layers. Instead of using photos, create a graphic representation of the content that emphasizes the features you want people to notice. Similarly, if your app has an interface that people recognize, don’t just replicate standard UI components or use app screenshots in your icon." }, { "type": "paragraph", "text": "Don’t use replicas of Apple hardware products. Apple products are copyrighted and can’t be reproduced in your app icons." } ] }, { "heading": "Visual effects", "level": 2, "content": [ { "type": "paragraph", "text": "Let the system handle blurring and other visual effects. The system dynamically applies visual effects to your app icon layers, so there’s no need to include specular highlights, drop shadows between layers, beveled edges, blurs, glows, and other effects. In addition to interfering with system-provided effects, custom effects are static, whereas the system supplies dynamic ones. If you do include custom visual effects on your icon layers, use them intentionally and test carefully with Icon Composer, in Simulator, or on device to make sure they appear as expected and don’t conflict with system effects." }, { "type": "paragraph", "text": "Create layer groupings to apply effects to multiple layers at once. System effects typically occur on individual layers. If it makes sense for your design, however, you can group several layers together in Icon Composer or your design tool so effects occur at the group level." } ] }, { "heading": "Appearances", "level": 2, "content": [ { "type": "paragraph", "text": "In iOS, iPadOS, and macOS, people can choose whether their Home Screen app icons are default, dark, clear, or tinted in appearance. For example, someone may want to personalize their app icon appearance to complement their wallpaper. You can design app icon variants for every appearance variant, and the system automatically generates variants you don’t provide." }, { "type": "paragraph", "text": "Keep your icon’s features consistent across appearances. To create a seamless experience, keep your icon’s core visual features the same in the default, dark, clear, and tinted appearances. Avoid creating custom icon variants that swap elements in and out with each variant, which may make it harder for people to find your app when they switch appearances." }, { "type": "paragraph", "text": "Design dark and tinted icons that feel at home beside system app icons and widgets. You can preserve the color palette of your default icon, but be mindful that dark icons are more subdued, and clear and tinted icons are even more so. A great app icon is visible, legible, and recognizable, regardless of its appearance variant." }, { "type": "paragraph", "text": "Use your light app icon as the basis for your dark icon. Choose complementary colors that reflect the default design, and avoid excessively bright images. Color backgrounds generally offer the greatest contrast in dark icons. For guidance, see Dark Mode." }, { "type": "paragraph", "text": "Consider offering alternate app icons. In iOS, iPadOS, tvOS, and compatible apps running in visionOS, it’s possible to let people visit your app’s settings to choose an alternate version of your app icon. For example, a sports app might offer icons for different teams, letting someone choose their favorite. If you offer this capability, make sure each icon you design remains closely related to your content and experience. Avoid creating one someone might mistake for another app." }, { "type": "note", "text": "NoteAlternate app icons in iOS and iPadOS require their own dark, clear, and tinted variants. As with your default app icon, all alternate and variant icons are subject to app review and must adhere to the App Review Guidelines." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, or macOS." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "Include a safe zone to ensure the system doesn’t crop your content. When someone focuses your app icon, the system may crop content around the edges as the icon scales and moves. To ensure that your icon’s content is always visible, keep a safe zone around it. Be aware that the safe zone can vary, depending on the image size, layer depth, and motion, and the system crops foreground layers more than background layers." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "Avoid adding a shape that’s intended to look like a hole or concave area to the background layer. The system-added shadow and specular highlights can make such a shape stand out instead of recede." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Avoid using black for your icon’s background. Lighten a black background so the icon doesn’t blend into the display background." } ] }, { "heading": "Specifications", "level": 2, "content": [ { "type": "paragraph", "text": "The layout, size, style, and appearances of app icons vary by platform." }, { "type": "table", "rows": [ [ "Platform", "Layout shape", "Icon shape after system masking", "Layout size", "Style", "Appearances" ], [ "iOS, iPadOS, macOS", "Square", "Rounded rectangle (square)", "1024x1024 px", "Layered", "Default, dark, clear light, clear dark, tinted light, tinted dark" ], [ "tvOS", "Rectangle (landscape)", "Rounded rectangle (rectangular)", "800x480 px", "Layered (Parallax)", "N/A" ], [ "visionOS", "Square", "Circular", "1024x1024 px", "Layered (3D)", "N/A" ], [ "watchOS", "Square", "Circular", "1088x1088 px", "Layered", "N/A" ] ] }, { "type": "paragraph", "text": "The system automatically scales your icon to produce smaller variants that appear in certain locations, such as Settings and notifications." }, { "type": "paragraph", "text": "App icons support the following color spaces:" }, { "type": "list", "items": [ "sRGB (color)", "Gray Gamma 2.2 (grayscale)", "Display P3 (wide-gamut color in iOS, iPadOS, macOS, tvOS, and watchOS only)" ] } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Design Resources" }, { "type": "paragraph", "text": "Icon Composer" }, { "type": "paragraph", "text": "Icons" }, { "type": "paragraph", "text": "Images" }, { "type": "paragraph", "text": "Dark Mode" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Creating your app icon using Icon Composer" }, { "type": "paragraph", "text": "Configuring your app icon using an asset catalog" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Updated guidance to reflect layered icons, consistency across platforms, and best practices for Liquid Glass." ], [ "June 10, 2024", "Added guidance for creating dark and tinted app icon variants for iOS and iPadOS." ], [ "January 31, 2024", "Clarified platform availability for alternate app icons." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "September 14, 2022", "Added specifications for Apple Watch Ultra." ] ] } ] } ], "platforms": [], "related": [ { "title": "Layer design", "url": "/design/human-interface-guidelines/app-icons#Layer-design" }, { "title": "Icon shape", "url": "/design/human-interface-guidelines/app-icons#Icon-shape" }, { "title": "Design", "url": "/design/human-interface-guidelines/app-icons#Design" }, { "title": "Visual effects", "url": "/design/human-interface-guidelines/app-icons#Visual-effects" }, { "title": "Appearances", "url": "/design/human-interface-guidelines/app-icons#Appearances" }, { "title": "Dark Mode", "url": "/design/human-interface-guidelines/dark-mode" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/app-icons#Platform-considerations" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/app-icons#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/app-icons#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/app-icons#watchOS" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/app-icons#Specifications" }, { "title": "Resources", "url": "/design/human-interface-guidelines/app-icons#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/app-icons#Related" }, { "title": "Icons", "url": "/design/human-interface-guidelines/icons" }, { "title": "Images", "url": "/design/human-interface-guidelines/images" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/app-icons#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/app-icons#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/app-icons#Change-log" } ], "image_count": 3 }, { "title": "Branding", "url": "https://developer.apple.com/design/human-interface-guidelines/branding", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "In addition to expressing your brand in your app icon and throughout your experience, you have several opportunities to highlight it within the App Store. For guidance, see App Store Marketing Guidelines." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Use your brand’s unique voice and tone in all the written communication you display. For example, your brand might convey feelings of encouragement and optimism by using plain words, occasional exclamation marks and emoji, and simple sentence structures." }, { "type": "paragraph", "text": "Consider choosing an accent color. On most platforms, you can specify a color that the system applies to app elements like interface icons, buttons, and text. In macOS, people can also choose their own accent color that the system can use in place of the color an app specifies. For guidance, see Color." }, { "type": "paragraph", "text": "Consider using a custom font. If your brand is strongly associated with a specific font, be sure that it’s legible at all sizes and supports accessibility features like bold text and larger type. It can work well to use a custom font for headlines and subheadings while using a system font for body copy and captions, because the system fonts are designed for optimal legibility at small sizes. For guidance, see Typography." }, { "type": "paragraph", "text": "Ensure branding always defers to content. Using screen space for an element that does nothing but display a brand asset can mean there’s less room for the content people care about. Aim to incorporate branding in refined, unobtrusive ways that don’t distract people from your experience." }, { "type": "paragraph", "text": "Help people feel comfortable by using standard patterns consistently. Even a highly stylized interface can be approachable if it maintains familiar behaviors. For example, place UI components in expected locations and use standard symbols to represent common actions." }, { "type": "paragraph", "text": "Resist the temptation to display your logo throughout your app or game unless it’s essential for providing context. People seldom need to be reminded which app they’re using, and it’s usually better to use the space to give people valuable information and controls." }, { "type": "paragraph", "text": "Avoid using a launch screen as a branding opportunity. Some platforms use a launch screen to minimize the startup experience, while simultaneously giving the app or game a little time to load resources (for guidance, see Launch screens). A launch screen disappears too quickly to convey any information, but you might consider displaying a welcome or onboarding screen that incorporates your branding content at the beginning of your experience. For guidance, see Onboarding." }, { "type": "paragraph", "text": "Follow Apple’s trademark guidelines. Apple trademarks must not appear in your app name or images. See Apple Trademark List and Guidelines for Using Apple Trademarks." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Marketing resources and identity guidelines" }, { "type": "paragraph", "text": "Show more with app previews" }, { "type": "paragraph", "text": "Color" } ] } ], "platforms": [], "related": [ { "title": "app icon", "url": "https://developer.apple.com/design/human-interface-guidelines/app-icons" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/branding#Best-practices" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Launch screens", "url": "/design/human-interface-guidelines/launching#Launch-screens" }, { "title": "Onboarding", "url": "/design/human-interface-guidelines/onboarding" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/branding#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/branding#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/branding#Related" } ], "image_count": 0 }, { "title": "Buttons", "url": "https://developer.apple.com/design/human-interface-guidelines/buttons", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Versatile and highly customizable, buttons give people simple, familiar ways to do tasks in your app. In general, a button combines three attributes to clearly communicate its function:" }, { "type": "list", "items": [ "Style. A visual style based on size, color, and shape.", "Content. A symbol (or icon), text label, or both that a button displays to convey its purpose.", "Role. A system-defined role that identifies a button’s semantic meaning and can affect its appearance." ] }, { "type": "paragraph", "text": "There are also many button-like components that have distinct appearances and behaviors for specific use cases, like toggles, pop-up buttons, and segmented controls." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "When buttons are instantly recognizable and easy to understand, an app tends to feel intuitive and well designed." }, { "type": "paragraph", "text": "Make buttons easy for people to use. It’s essential to include enough space around a button so that people can visually distinguish it from surrounding components and content. Giving a button enough space is also critical for helping people select or activate it, regardless of the method of input they use. As a general rule, a button needs a hit region of at least 44x44 pt — in visionOS, 60x60 pt — to ensure that people can select it easily, whether they use a fingertip, a pointer, their eyes, or a remote." }, { "type": "paragraph", "text": "Always include a press state for a custom button. Without a press state, a button can feel unresponsive, making people wonder if it’s accepting their input." } ] }, { "heading": "Style", "level": 2, "content": [ { "type": "paragraph", "text": "System buttons offer a range of styles that support customization while providing built-in interaction states, accessibility support, and appearance adaptation. Different platforms define different styles that help you communicate hierarchies of actions in your app." }, { "type": "paragraph", "text": "In general, use a button that has a prominent visual style for the most likely action in a view. To draw people’s attention to a specific button, use a prominent button style so the system can apply an accent color to the button’s background. Buttons that use color tend to be the most visually distinctive, helping people quickly identify the actions they’re most likely to use. Keep the number of prominent buttons to one or two per view. Presenting too many prominent buttons increases cognitive load, requiring people to spend more time considering options before making a choice." }, { "type": "paragraph", "text": "Use style — not size — to visually distinguish the preferred choice among multiple options. When you use buttons of the same size to offer two or more options, you signal that the options form a coherent set of choices. By contrast, placing two buttons of different sizes near each other can make the interface look confusing and inconsistent. If you want to highlight the preferred or most likely option in a set, use a more prominent button style for that option and a less prominent style for the remaining ones." }, { "type": "paragraph", "text": "Avoid applying a similar color to button labels and content layer backgrounds. If your app already has bright, colorful content in the content layer, prefer using the default monochromatic appearance of button labels. For more guidance, see Liquid Glass color." } ] }, { "heading": "Content", "level": 2, "content": [ { "type": "paragraph", "text": "Ensure that each button clearly communicates its purpose. Depending on the platform, a button can contain a symbol (or icon), a text label, or both to help people understand what it does." }, { "type": "note", "text": "NoteIn macOS and visionOS, the system displays a tooltip after people hover over a button for a moment. A tooltip displays a brief phrase that explains what a button does; for guidance, see Offering help." }, { "type": "paragraph", "text": "Try to associate familiar actions with familiar icons. For example, people can predict that a button containing the square.and.arrow.up symbol will help them perform share-related activities. If it makes sense to use an icon in your button, consider using an existing or customized symbol. For a list of symbols that represent common actions, see Standard icons." }, { "type": "paragraph", "text": "Consider using text when a short label communicates more clearly than an icon. To use text, write a few words that succinctly describe what the button does. Using title-style capitalization, consider starting the label with a verb to help convey the button’s action — for example, a button that lets people add items to their shopping cart might use the label “Add to Cart.”" } ] }, { "heading": "Role", "level": 2, "content": [ { "type": "paragraph", "text": "A system button can have one of the following roles:" }, { "type": "list", "items": [ "Normal. No specific meaning.", "Primary. The button is the default button — the button people are most likely to choose.", "Cancel. The button cancels the current action.", "Destructive. The button performs an action that can result in data destruction." ] }, { "type": "paragraph", "text": "A button’s role can have additional effects on its appearance. For example, a primary button uses an app’s accent color, whereas a destructive button uses the system red color." }, { "type": "paragraph", "text": "Assign the primary role to the button people are most likely to choose. When a primary button responds to the Return key, it makes it easy for people to quickly confirm their choice. In addition, when the button is in a temporary view — like a sheet, an editable view, or an alert — assigning it the primary role means that the view can automatically close when people press Return." }, { "type": "paragraph", "text": "Don’t assign the primary role to a button that performs a destructive action, even if that action is the most likely choice. Because of its visual prominence, people sometimes choose a primary button without reading it first. Help people avoid losing content by assigning the primary role to nondestructive buttons." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for tvOS." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "Configure a button to display an activity indicator when you need to provide feedback about an action that doesn’t instantly complete. Displaying an activity indicator within a button can save space in your user interface while clearly communicating the reason for the delay. To help clarify what’s happening, you can also configure the button to display a different label alongside the activity indicator. For example, the label “Checkout” could change to “Checking out…” while the activity indicator is visible. When a delay occurs after people click or tap your configured button, the system displays the activity indicator next to the original or alternative label, hiding the button image, if there is one." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "Several specific button types are unique to macOS." } ] }, { "heading": "Push buttons", "level": 4, "content": [ { "type": "paragraph", "text": "The standard button type in macOS is known as a push button. You can configure a push button to display text, a symbol, an icon, or an image, or a combination of text and image content. Push buttons can act as the default button in a view and you can tint them." }, { "type": "paragraph", "text": "Use a flexible-height push button only when you need to display tall or variable height content. Flexible-height buttons support the same configurations as regular push buttons — and they use the same corner radius and content padding — so they look consistent with other buttons in your interface. If you need to present a button that contains two lines of text or a tall icon, use a flexible-height button; otherwise, use a standard push button. For developer guidance, see NSButton.BezelStyle.flexiblePush." }, { "type": "paragraph", "text": "Append a trailing ellipsis to the title when a push button opens another window, view, or app. Throughout the system, an ellipsis in a control title signals that people can provide additional input. For example, the Edit buttons in the AutoFill pane of Safari Settings include ellipses because they open other views that let people modify autofill values." }, { "type": "paragraph", "text": "Consider supporting spring loading. On systems with a Magic Trackpad, spring loading lets people activate a button by dragging selected items over it and force clicking — that is, pressing harder — without dropping the selected items. After force clicking, people can continue dragging the items, possibly to perform additional actions." } ] }, { "heading": "Square buttons", "level": 4, "content": [ { "type": "paragraph", "text": "A square button (also known as a gradient button) initiates an action related to a view, like adding or removing rows in a table." }, { "type": "paragraph", "text": "Square buttons contain symbols or icons — not text — and you can configure them to behave like push buttons, toggles, or pop-up buttons. The buttons appear in close proximity to their associated view — usually within or beneath it — so people know which view the buttons affect." }, { "type": "paragraph", "text": "Use square buttons in a view, not in the window frame. Square buttons aren’t intended for use in toolbars or status bars. If you need a button in a toolbar, use a toolbar item." }, { "type": "paragraph", "text": "Prefer using a symbol in a square button. SF Symbols provides a wide range of symbols that automatically receive appropriate coloring in their default state and in response to user interaction." }, { "type": "paragraph", "text": "Avoid using labels to introduce square buttons. Because square buttons are closely connected with a specific view, their purpose is generally clear without the need for descriptive text." }, { "type": "paragraph", "text": "For developer guidance, see NSButton.BezelStyle.smallSquare." } ] }, { "heading": "Help buttons", "level": 4, "content": [ { "type": "paragraph", "text": "A help button appears within a view and opens app-specific help documentation." }, { "type": "paragraph", "text": "Help buttons are circular, consistently sized buttons that contain a question mark. For guidance on creating help documentation, see Offering help." }, { "type": "paragraph", "text": "Use the system-provided help button to display your help documentation. People are familiar with the appearance of the standard help button and know that choosing it opens help content." }, { "type": "paragraph", "text": "When possible, open the help topic that’s related to the current context. For example, the help button in the Rules pane of Mail settings opens the Mail User Guide to a help topic that explains how to change these settings. If no specific help topic applies directly to the current context, open the top level of your app’s help documentation when people choose a help button." }, { "type": "paragraph", "text": "Include no more than one help button per window. Multiple help buttons in the same context make it hard for people to predict the result of clicking one." }, { "type": "paragraph", "text": "Position help buttons where people expect to find them. Use the following locations for guidance." }, { "type": "table", "rows": [ [ "View style", "Help button location" ], [ "Dialog with dismissal buttons (like OK and Cancel)", "Lower corner, opposite to the dismissal buttons and vertically aligned with them" ], [ "Dialog without dismissal buttons", "Lower-left or lower-right corner" ], [ "Settings window or pane", "Lower-left or lower-right corner" ] ] }, { "type": "paragraph", "text": "Use a help button within a view, not in the window frame. For example, avoid placing a help button in a toolbar or status bar." }, { "type": "paragraph", "text": "Avoid displaying text that introduces a help button. People know what a help button does, so they don’t need additional descriptive text." } ] }, { "heading": "Image buttons", "level": 4, "content": [ { "type": "paragraph", "text": "An image button appears in a view and displays an image, symbol, or icon. You can configure an image button to behave like a push button, toggle, or pop-up button." }, { "type": "paragraph", "text": "Use an image button in a view, not in the window frame. For example, avoid placing an image button in a toolbar or status bar. If you need to use an image as a button in a toolbar, use a toolbar item. See Toolbars." }, { "type": "paragraph", "text": "Include about 10 pixels of padding between the edges of the image and the button edges. An image button’s edges define its clickable area even when they aren’t visible. Including padding ensures that a click registers correctly even if it’s not precisely within the image. In general, avoid including a system-provided border in an image button; for developer guidance, see isBordered." }, { "type": "paragraph", "text": "If you need to include a label, position it below the image button. For related guidance, see Labels." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "A visionOS button typically includes a visible background that can help people see it, and the button plays sound to provide feedback when people interact with it." }, { "type": "paragraph", "text": "There are three standard button shapes in visionOS. Typically, an icon-only button uses a circle shape, a text-only button uses a roundedRectangle or capsule shape, and a button that includes both an icon and text uses the capsule shape." }, { "type": "paragraph", "text": "visionOS buttons use different visual styles to communicate four different interaction states." }, { "type": "paragraph", "text": "Idle" }, { "type": "paragraph", "text": "Hover" }, { "type": "paragraph", "text": "Selected" }, { "type": "paragraph", "text": "Unavailable" }, { "type": "note", "text": "NoteIn visionOS, buttons don’t support custom hover effects." }, { "type": "paragraph", "text": "In addition to the four states shown above, a button can also reveal a tooltip when people look at it for a brief time. In general, buttons that contain text don’t need to display a tooltip because the button’s descriptive label communicates what it does." }, { "type": "paragraph", "text": "In visionOS, buttons can have the following sizes." }, { "type": "table", "rows": [ [ "Shape", "Mini (28 pt)", "Small (32 pt)", "Regular (44 pt)", "Large (52 pt)", "Extra large (64 pt)" ], [ "Circular", "", "", "", "", "" ], [ "Capsule (text only)", "", "", "", "", "" ], [ "Capsule (text and icon)", "", "", "", "", "" ], [ "Rounded rectangle", "", "", "", "", "" ] ] }, { "type": "paragraph", "text": "Prefer buttons that have a discernible background shape and fill. It tends to be easier for people to see a button when it’s enclosed in a shape that uses a contrasting background fill. The exception is a button in a toolbar, context menu, alert, or ornament where the shape and material of the larger component make the button comfortably visible. The following guidelines can help you ensure that a button looks good in different contexts:" }, { "type": "list", "items": [ "When a button appears on top of a glass window, use the thin material as the button’s background.", "When a button appears floating in space, use the glass material for its background." ] }, { "type": "paragraph", "text": "Avoid creating a custom button that uses a white background fill and black text or icons. The system reserves this visual style to convey the toggled state." }, { "type": "paragraph", "text": "In general, prefer circular or capsule-shape buttons. People’s eyes tend to be drawn toward the corners in a shape, making it difficult to keep looking at the shape’s center. The more rounded a button’s shape, the easier it is for people to look steadily at it. When you need to display a button by itself, prefer a capsule-shape button." }, { "type": "paragraph", "text": "Provide enough space around a button to make it easy for people to look at it. Aim to place buttons so their centers are always at least 60 pts apart. If your buttons measure 60 pts or larger, add 4 pts of padding around them to keep the hover effect from overlapping. Also, it’s usually best to avoid displaying small or mini buttons in a vertical stack or horizontal row." }, { "type": "paragraph", "text": "Choose the right shape if you need to display text-labeled buttons in a stack or row. Specifically, prefer the rounded-rectangle shape in a vertical stack of buttons and prefer the capsule shape in a horizontal row of buttons." }, { "type": "paragraph", "text": "Use standard controls to take advantage of the audible feedback sounds people already know. Audible feedback is especially important in visionOS, because the system doesn’t play haptics." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "watchOS displays all inline buttons using the capsule button shape. When you place a button inline with content, it gains a material effect that contrasts with the background to ensure legibility." }, { "type": "paragraph", "text": "Use a toolbar to place buttons in the corners. The system automatically moves the time and title to accommodate toolbar buttons. The system also applies the Liquid Glass appearance to toolbar buttons, providing a clear visual distinction from the content beneath them." }, { "type": "paragraph", "text": "Prefer buttons that span the width of the screen for primary actions in your app. Full-width buttons look better and are easier for people to tap. If two buttons must share the same horizontal space, use the same height for both, and use images or short text titles for each button’s content." }, { "type": "paragraph", "text": "Use toolbar buttons to provide either navigation to related areas or contextual actions for the view’s content. These buttons provide access to additional information or secondary actions for the view’s content." }, { "type": "paragraph", "text": "Use the same height for vertical stacks of one- and two-line text buttons. As much as possible, use identical button heights for visual consistency." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Pop-up buttons" }, { "type": "paragraph", "text": "Pull-down buttons" }, { "type": "paragraph", "text": "Toggles" }, { "type": "paragraph", "text": "Segmented controls" }, { "type": "paragraph", "text": "Location button" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Button — SwiftUI" }, { "type": "paragraph", "text": "UIButton — UIKit" }, { "type": "paragraph", "text": "NSButton — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Updated guidance for Liquid Glass." ], [ "June 9, 2025", "Updated guidance for button styles and content." ], [ "February 2, 2024", "Noted that visionOS buttons don’t support custom hover effects." ], [ "December 5, 2023", "Clarified some terminology and guidance for buttons in visionOS." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "June 5, 2023", "Updated guidance for using buttons in watchOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "toggles", "url": "/design/human-interface-guidelines/toggles" }, { "title": "pop-up buttons", "url": "/design/human-interface-guidelines/pop-up-buttons" }, { "title": "segmented controls", "url": "/design/human-interface-guidelines/segmented-controls" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/buttons#Best-practices" }, { "title": "Style", "url": "/design/human-interface-guidelines/buttons#Style" }, { "title": "Liquid Glass color", "url": "/design/human-interface-guidelines/color#Liquid-Glass-color" }, { "title": "Content", "url": "/design/human-interface-guidelines/buttons#Content" }, { "title": "Offering help", "url": "/design/human-interface-guidelines/offering-help" }, { "title": "symbol", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Standard icons", "url": "/design/human-interface-guidelines/icons#Standard-icons" }, { "title": "Role", "url": "/design/human-interface-guidelines/buttons#Role" }, { "title": "sheet", "url": "/design/human-interface-guidelines/sheets" }, { "title": "alert", "url": "/design/human-interface-guidelines/alerts" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/buttons#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/buttons#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/buttons#macOS" }, { "title": "Push buttons", "url": "/design/human-interface-guidelines/buttons#Push-buttons" }, { "title": "Square buttons", "url": "/design/human-interface-guidelines/buttons#Square-buttons" }, { "title": "toolbar", "url": "https://developer.apple.com/design/human-interface-guidelines/toolbars" }, { "title": "Help buttons", "url": "/design/human-interface-guidelines/buttons#Help-buttons" }, { "title": "Image buttons", "url": "/design/human-interface-guidelines/buttons#Image-buttons" }, { "title": "Toolbars", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "Labels", "url": "/design/human-interface-guidelines/labels" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/buttons#visionOS" }, { "title": "ornament", "url": "/design/human-interface-guidelines/ornaments" }, { "title": "window", "url": "/design/human-interface-guidelines/windows#visionOS" }, { "title": "glass material", "url": "/design/human-interface-guidelines/materials#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/buttons#watchOS" }, { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "Resources", "url": "/design/human-interface-guidelines/buttons#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/buttons#Related" }, { "title": "Pull-down buttons", "url": "/design/human-interface-guidelines/pull-down-buttons" }, { "title": "Location button", "url": "/design/human-interface-guidelines/privacy#Location-button" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/buttons#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/buttons#Change-log" } ], "image_count": 0 }, { "title": "Color", "url": "https://developer.apple.com/design/human-interface-guidelines/color", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "The system defines colors that look good on various backgrounds and appearance modes, and can automatically adapt to vibrancy and accessibility settings. Using system colors is a convenient way to make your experience feel at home on the device." }, { "type": "paragraph", "text": "You may also want to use custom colors to enhance the visual experience of your app or game and express its unique personality. The following guidelines can help you use color in ways that people appreciate, regardless of whether you use system-defined or custom colors." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Avoid using the same color to mean different things. Use color consistently throughout your interface, especially when you use it to help communicate information like status or interactivity. For example, if you use your brand color to indicate that a borderless button is interactive, using the same or similar color to stylize noninteractive text is confusing." }, { "type": "paragraph", "text": "Make sure all your app’s colors work well in light, dark, and increased contrast contexts. iOS, iPadOS, macOS, and tvOS offer both light and dark appearance settings. System colors vary subtly depending on the system appearance, adjusting to ensure proper color differentiation and contrast for text, symbols, and other elements. With the Increase Contrast setting turned on, the color differences become far more apparent. When possible, use system colors, which already define variants for all these contexts. If you define a custom color, make sure to supply light and dark variants, and an increased contrast option for each variant that provides a significantly higher amount of visual differentiation. Even if your app ships in a single appearance mode, provide both light and dark colors to support Liquid Glass adaptivity in these contexts." }, { "type": "paragraph", "text": "Default (light)" }, { "type": "paragraph", "text": "Increased contrast (light)" }, { "type": "paragraph", "text": "Default (dark)" }, { "type": "paragraph", "text": "Increased contrast (dark)" }, { "type": "paragraph", "text": "Test your app’s color scheme under a variety of lighting conditions. Colors can look different when you view your app outside on a sunny day or in dim light. In bright surroundings, colors look darker and more muted. In dark environments, colors appear bright and saturated. In visionOS, colors can look different depending on the colors of a wall or object in a person’s physical surroundings and how it reflects light. Adjust app colors to provide an optimal viewing experience in the majority of use cases." }, { "type": "paragraph", "text": "Test your app on different devices. For example, the True Tone display — available on certain iPhone, iPad, and Mac models — uses ambient light sensors to automatically adjust the white point of the display to adapt to the lighting conditions of the current environment. Apps that primarily support reading, photos, video, and gaming can strengthen or weaken this effect by specifying a white point adaptivity style (for developer guidance, see UIWhitePointAdaptivityStyle). Test tvOS apps on multiple brands of HD and 4K TVs, and with different display settings. You can also test the appearance of your app using different color profiles on a Mac — such as P3 and Standard RGB (sRGB) — by choosing a profile in System Settings > Displays. For guidance, see Color management." }, { "type": "paragraph", "text": "Consider how artwork and translucency affect nearby colors. Variations in artwork sometimes warrant changes to nearby colors to maintain visual continuity and prevent interface elements from becoming overpowering or underwhelming. Maps, for example, displays a light color scheme when in map mode but switches to a dark color scheme when in satellite mode. Colors can also appear different when placed behind or applied to a translucent element like a toolbar." }, { "type": "paragraph", "text": "If your app lets people choose colors, prefer system-provided color controls where available. Using built-in color pickers provides a consistent user experience, in addition to letting people save a set of colors they can access from any app. For developer guidance, see ColorPicker." } ] }, { "heading": "Inclusive color", "level": 2, "content": [ { "type": "paragraph", "text": "Avoid relying solely on color to differentiate between objects, indicate interactivity, or communicate essential information. When you use color to convey information, be sure to provide the same information in alternative ways so people with color blindness or other visual disabilities can understand it. For example, you can use text labels or glyph shapes to identify objects or states." }, { "type": "paragraph", "text": "Avoid using colors that make it hard to perceive content in your app. For example, insufficient contrast can cause icons and text to blend with the background and make content hard to read, and people who are color blind might not be able to distinguish some color combinations. For guidance, see Accessibility." }, { "type": "paragraph", "text": "Consider how the colors you use might be perceived in other countries and cultures. For example, red communicates danger in some cultures, but has positive connotations in other cultures. Make sure the colors in your app send the message you intend." }, { "type": "paragraph", "text": "Green indicates a positive trend in the Stocks app in English." }, { "type": "paragraph", "text": "Red indicates a positive trend in the Stocks app in Chinese." } ] }, { "heading": "System colors", "level": 2, "content": [ { "type": "paragraph", "text": "Avoid hard-coding system color values in your app. Documented color values are for your reference during the app design process. The actual color values may fluctuate from release to release, based on a variety of environmental variables. Use APIs like Color to apply system colors." }, { "type": "paragraph", "text": "iOS, iPadOS, macOS, and visionOS also define sets of dynamic system colors that match the color schemes of standard UI components and automatically adapt to both light and dark contexts. Each dynamic color is semantically defined by its purpose, rather than its appearance or color values. For example, some colors represent view backgrounds at different levels of hierarchy and other colors represent foreground content, such as labels, links, and separators." }, { "type": "paragraph", "text": "Avoid redefining the semantic meanings of dynamic system colors. To ensure a consistent experience and ensure your interface looks great when the appearance of the platform changes, use dynamic system colors as intended. For example, don’t use the separator color as a text color, or secondary text label color as a background color." } ] }, { "heading": "Liquid Glass color", "level": 2, "content": [ { "type": "paragraph", "text": "By default, Liquid Glass has no inherent color, and instead takes on colors from the content directly behind it. You can apply color to some Liquid Glass elements, giving them the appearance of colored or stained glass. This is useful for drawing emphasis to a specific control, like a primary call to action, and is the approach the system uses for prominent button styling. Symbols or text labels on Liquid Glass controls can also have color." }, { "type": "paragraph", "text": "Controls can use color in the Liquid Glass background, like in a primary action button." }, { "type": "paragraph", "text": "Symbols and text that appear on Liquid Glass can have color, like in a selected tab bar item." }, { "type": "paragraph", "text": "By default, Liquid Glass picks up the color from the content layer behind it." }, { "type": "paragraph", "text": "For smaller elements like toolbars and tab bars, the system can adapt Liquid Glass between a light and dark appearance in response to the underlying content. By default, symbols and text on these elements follow a monochromatic color scheme, becoming darker when the underlying content is light, and lighter when it’s dark. Liquid Glass appears more opaque in larger elements like sidebars to preserve legibility over complex backgrounds and accommodate richer content on the material’s surface." }, { "type": "paragraph", "text": "Apply color sparingly to the Liquid Glass material, and to symbols or text on the material. If you apply color, reserve it for elements that truly benefit from emphasis, such as status indicators or primary actions. To emphasize primary actions, apply color to the background rather than to symbols or text. For example, the system applies the app accent color to the background in prominent buttons — such as the Done button — to draw attention and elevate their visual prominence. Refrain from adding color to the background of multiple controls." }, { "type": "paragraph", "text": "Avoid using similar colors in control labels if your app has a colorful background. While color can make apps more visually appealing, playful, or reflective of your brand, too much color can be overwhelming and make control labels more difficult to read. If your app features colorful backgrounds or visually rich content, prefer a monochromatic appearance for toolbars and tab bars, or choose an accent color with sufficient visual differentiation. By contrast, in apps with primarily monochromatic content or backgrounds, choosing your brand color as the app accent color can be an effective way to tailor your app experience and reflect your company’s identity." }, { "type": "paragraph", "text": "Be aware of the placement of color in the content layer. Make sure your interface maintains sufficient contrast by avoiding overlap of similar colors in the content layer and controls when possible. Although colorful content might intermittently scroll underneath controls, make sure its default or resting state — like the top of a screen of scrollable content — maintains clear legibility." } ] }, { "heading": "Color management", "level": 2, "content": [ { "type": "paragraph", "text": "A color space represents the colors in a color model like RGB or CMYK. Common color spaces — sometimes called gamuts — are sRGB and Display P3." }, { "type": "paragraph", "text": "A color profile describes the colors in a color space using, for example, mathematical formulas or tables of data that map colors to numerical representations. An image embeds its color profile so that a device can interpret the image’s colors correctly and reproduce them on a display." }, { "type": "paragraph", "text": "Apply color profiles to your images. Color profiles help ensure that your app’s colors appear as intended on different displays. The sRGB color space produces accurate colors on most displays." }, { "type": "paragraph", "text": "Use wide color to enhance the visual experience on compatible displays. Wide color displays support a P3 color space, which can produce richer, more saturated colors than sRGB. As a result, photos and videos that use wide color are more lifelike, and visual data and status indicators that use wide color can be more meaningful. When appropriate, use the Display P3 color profile at 16 bits per pixel (per channel) and export images in PNG format. Note that you need to use a wide color display to design wide color images and select P3 colors." }, { "type": "paragraph", "text": "Provide color space–specific image and color variations if necessary. In general, P3 colors and images appear fine on sRGB displays. Occasionally, it may be hard to distinguish two very similar P3 colors when viewing them on an sRGB display. Gradients that use P3 colors can also sometimes appear clipped on sRGB displays. To avoid these issues and to ensure visual fidelity on both wide color and sRGB displays, you can use the asset catalog of your Xcode project to provide different versions of images and colors for each color space." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "iOS defines two sets of dynamic background colors — system and grouped — each of which contains primary, secondary, and tertiary variants that help you convey a hierarchy of information. In general, use the grouped background colors (systemGroupedBackground, secondarySystemGroupedBackground, and tertiarySystemGroupedBackground) when you have a grouped table view; otherwise, use the system set of background colors (systemBackground, secondarySystemBackground, and tertiarySystemBackground)." }, { "type": "paragraph", "text": "With both sets of background colors, you generally use the variants to indicate hierarchy in the following ways:" }, { "type": "list", "items": [ "Primary for the overall view", "Secondary for grouping content or elements within the overall view", "Tertiary for grouping content or elements within secondary elements" ] }, { "type": "paragraph", "text": "For foreground content, iOS defines the following dynamic colors:" }, { "type": "table", "rows": [ [ "Color", "Use for…", "UIKit API" ], [ "Label", "A text label that contains primary content.", "label" ], [ "Secondary label", "A text label that contains secondary content.", "secondaryLabel" ], [ "Tertiary label", "A text label that contains tertiary content.", "tertiaryLabel" ], [ "Quaternary label", "A text label that contains quaternary content.", "quaternaryLabel" ], [ "Placeholder text", "Placeholder text in controls or text views.", "placeholderText" ], [ "Separator", "A separator that allows some underlying content to be visible.", "separator" ], [ "Opaque separator", "A separator that doesn’t allow any underlying content to be visible.", "opaqueSeparator" ], [ "Link", "Text that functions as a link.", "link" ] ] } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "macOS defines the following dynamic system colors (you can also view them in the Developer palette of the standard Color panel):" }, { "type": "table", "rows": [ [ "Color", "Use for…", "AppKit API" ], [ "Alternate selected control text color", "The text on a selected surface in a list or table.", "alternateSelectedControlTextColor" ], [ "Alternating content background colors", "The backgrounds of alternating rows or columns in a list, table, or collection view.", "alternatingContentBackgroundColors" ], [ "Control accent", "The accent color people select in System Settings.", "controlAccentColor" ], [ "Control background color", "The background of a large interface element, such as a browser or table.", "controlBackgroundColor" ], [ "Control color", "The surface of a control.", "controlColor" ], [ "Control text color", "The text of a control that is available.", "controlTextColor" ], [ "Current control tint", "The system-defined control tint.", "currentControlTint" ], [ "Unavailable control text color", "The text of a control that’s unavailable.", "disabledControlTextColor" ], [ "Find highlight color", "The color of a find indicator.", "findHighlightColor" ], [ "Grid color", "The gridlines of an interface element, such as a table.", "gridColor" ], [ "Header text color", "The text of a header cell in a table.", "headerTextColor" ], [ "Highlight color", "The virtual light source onscreen.", "highlightColor" ], [ "Keyboard focus indicator color", "The ring that appears around the currently focused control when using the keyboard for interface navigation.", "keyboardFocusIndicatorColor" ], [ "Label color", "The text of a label containing primary content.", "labelColor" ], [ "Link color", "A link to other content.", "linkColor" ], [ "Placeholder text color", "A placeholder string in a control or text view.", "placeholderTextColor" ], [ "Quaternary label color", "The text of a label of lesser importance than a tertiary label, such as watermark text.", "quaternaryLabelColor" ], [ "Secondary label color", "The text of a label of lesser importance than a primary label, such as a label used to represent a subheading or additional information.", "secondaryLabelColor" ], [ "Selected content background color", "The background for selected content in a key window or view.", "selectedContentBackgroundColor" ], [ "Selected control color", "The surface of a selected control.", "selectedControlColor" ], [ "Selected control text color", "The text of a selected control.", "selectedControlTextColor" ], [ "Selected menu item text color", "The text of a selected menu.", "selectedMenuItemTextColor" ], [ "Selected text background color", "The background of selected text.", "selectedTextBackgroundColor" ], [ "Selected text color", "The color for selected text.", "selectedTextColor" ], [ "Separator color", "A separator between different sections of content.", "separatorColor" ], [ "Shadow color", "The virtual shadow cast by a raised object onscreen.", "shadowColor" ], [ "Tertiary label color", "The text of a label of lesser importance than a secondary label.", "tertiaryLabelColor" ], [ "Text background color", "The background color behind text.", "textBackgroundColor" ], [ "Text color", "The text in a document.", "textColor" ], [ "Under page background color", "The background behind a document’s content.", "underPageBackgroundColor" ], [ "Unemphasized selected content background color", "The selected content in a non-key window or view.", "unemphasizedSelectedContentBackgroundColor" ], [ "Unemphasized selected text background color", "A background for selected text in a non-key window or view.", "unemphasizedSelectedTextBackgroundColor" ], [ "Unemphasized selected text color", "Selected text in a non-key window or view.", "unemphasizedSelectedTextColor" ], [ "Window background color", "The background of a window.", "windowBackgroundColor" ], [ "Window frame text color", "The text in the window’s title bar area.", "windowFrameTextColor" ] ] } ] }, { "heading": "App accent colors", "level": 4, "content": [ { "type": "paragraph", "text": "Beginning in macOS 11, you can specify an accent color to customize the appearance of your app’s buttons, selection highlighting, and sidebar icons. The system applies your accent color when the current value in General > Accent color settings is multicolor." }, { "type": "paragraph", "text": "If people set their accent color setting to a value other than multicolor, the system applies their chosen color to the relevant items throughout your app, replacing your accent color. The exception is a sidebar icon that uses a fixed color you specify. Because a fixed-color sidebar icon uses a specific color to provide meaning, the system doesn’t override its color when people change the value of accent color settings. For guidance, see Sidebars." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "Consider choosing a limited color palette that coordinates with your app logo. Subtle use of color can help you communicate your brand while deferring to the content." }, { "type": "paragraph", "text": "Avoid using only color to indicate focus. Subtle scaling and responsive animation are the primary ways to denote interactivity when an element is in focus." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "Use color sparingly, especially on glass. Standard visionOS windows typically use the system-defined glass material, which lets light and objects from people’s physical surroundings and their space show through. Because the colors in these physical and virtual objects are visible through the glass, they can affect the legibility of colorful app content in the window. Prefer using color in places where it can help call attention to important information or show the relationship between parts of the interface." }, { "type": "paragraph", "text": "Prefer using color in bold text and large areas. Color in lightweight text or small areas can make them harder to see and understand." }, { "type": "paragraph", "text": "In a fully immersive experience, help people maintain visual comfort by keeping brightness levels balanced. Although using high contrast can help direct people’s attention to important content, it can also cause visual discomfort if people’s eyes have adjusted to low light or darkness. Consider making content fully bright only when the rest of the visual context is also bright. For example, avoid displaying a bright object on a very dark or black background, especially if the object flashes or moves." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Use background color to support existing content or supply additional information. Background color can establish a sense of place and help people recognize key content. For example, in Activity, each infographic view for the Move, Exercise, and Stand Activity rings has a background that matches the color of the ring. Use background color when you have something to communicate, rather than as a solely visual flourish. Avoid using full-screen background color in views that are likely to remain onscreen for long periods of time, such as in a workout or audio-playing app." }, { "type": "paragraph", "text": "Recognize that people might prefer graphic complications to use tinted mode instead of full color. The system can use a single color that’s based on the wearer’s selected color in a graphic complication’s images, gauges, and text. For guidance, see Complications." } ] }, { "heading": "System colors", "level": 3, "content": [ { "type": "table", "rows": [ [ "Name", "SwiftUI API", "Default (light)", "Default (dark)", "Increased contrast (light)", "Increased contrast (dark)" ], [ "Red", "red", "", "", "", "" ], [ "Orange", "orange", "", "", "", "" ], [ "Yellow", "yellow", "", "", "", "" ], [ "Green", "green", "", "", "", "" ], [ "Mint", "mint", "", "", "", "" ], [ "Teal", "teal", "", "", "", "" ], [ "Cyan", "cyan", "", "", "", "" ], [ "Blue", "blue", "", "", "", "" ], [ "Indigo", "indigo", "", "", "", "" ], [ "Purple", "purple", "", "", "", "" ], [ "Pink", "pink", "", "", "", "" ], [ "Brown", "brown", "", "", "", "" ] ] }, { "type": "paragraph", "text": "visionOS system colors use the default dark color values." } ] }, { "heading": "iOS, iPadOS system gray colors", "level": 3, "content": [ { "type": "table", "rows": [ [ "Name", "UIKit API", "Default (light)", "Default (dark)", "Increased contrast (light)", "Increased contrast (dark)" ], [ "Gray", "systemGray", "", "", "", "" ], [ "Gray (2)", "systemGray2", "", "", "", "" ], [ "Gray (3)", "systemGray3", "", "", "", "" ], [ "Gray (4)", "systemGray4", "", "", "", "" ], [ "Gray (5)", "systemGray5", "", "", "", "" ], [ "Gray (6)", "systemGray6", "", "", "", "" ] ] }, { "type": "paragraph", "text": "In SwiftUI, the equivalent of systemGray is gray." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Dark Mode" }, { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Materials" }, { "type": "paragraph", "text": "Apple Design Resources" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Color — SwiftUI" }, { "type": "paragraph", "text": "UIColor — UIKit" }, { "type": "paragraph", "text": "Color — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Updated guidance for Liquid Glass." ], [ "June 9, 2025", "Updated system color values, and added guidance for Liquid Glass." ], [ "February 2, 2024", "Distinguished UIKit and SwiftUI gray colors in iOS and iPadOS, and added guidance for balancing brightness levels in visionOS apps." ], [ "September 12, 2023", "Enhanced guidance for using background color in watchOS views, and added color swatches for tvOS." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "June 5, 2023", "Updated guidance for using background color in watchOS." ], [ "December 19, 2022", "Corrected RGB values for system mint color (Dark Mode) in iOS and iPadOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/color#Best-practices" }, { "title": "dark", "url": "/design/human-interface-guidelines/dark-mode" }, { "title": "System colors", "url": "/design/human-interface-guidelines/color#System-colors" }, { "title": "Color management", "url": "/design/human-interface-guidelines/color#Color-management" }, { "title": "Inclusive color", "url": "/design/human-interface-guidelines/color#Inclusive-color" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Liquid Glass color", "url": "/design/human-interface-guidelines/color#Liquid-Glass-color" }, { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/color#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/color#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/color#macOS" }, { "title": "App accent colors", "url": "/design/human-interface-guidelines/color#App-accent-colors" }, { "title": "Sidebars", "url": "/design/human-interface-guidelines/sidebars" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/color#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/color#visionOS" }, { "title": "material", "url": "/design/human-interface-guidelines/materials" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/color#watchOS" }, { "title": "Complications", "url": "/design/human-interface-guidelines/complications" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/color#Specifications" }, { "title": "iOS, iPadOS system gray colors", "url": "/design/human-interface-guidelines/color#iOS-iPadOS-system-gray-colors" }, { "title": "Resources", "url": "/design/human-interface-guidelines/color#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/color#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/color#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/color#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/color#Change-log" } ], "image_count": 0 }, { "title": "Complications", "url": "https://developer.apple.com/design/human-interface-guidelines/complications", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "People often prefer apps that provide multiple, powerful complications, because it gives them quick ways to view the data they care about, even when they don’t open the app." }, { "type": "paragraph", "text": "Most watch faces can display at least one complication; some can display four or more." }, { "type": "paragraph", "text": "Starting in watchOS 9, the system organizes complications (also known as accessories) into several families — like circular and inline — and defines some recommended layouts you can use to display your complication data. A watch face can specify the family it supports in each complication slot. Complications that work in earlier versions of watchOS can use the legacy templates, which define nongraphic complication styles that don’t take on a wearer’s selected color." }, { "type": "note", "text": "Developer notePrefer using WidgetKit to develop complications for watchOS 9 and later. For guidance, see Migrating ClockKit complications to WidgetKit. To support earlier versions of watchOS, continue to implement the ClockKit complication data source protocol (see CLKComplicationDataSource)." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Identify essential, dynamic content that people want to view at a glance. Although people can use a complication to quickly launch an app, the complication behavior they appreciate more is the display of relevant information that always feels up to date. A static complication that doesn’t display meaningful data may be less likely to remain in a prominent position on the watch face." }, { "type": "paragraph", "text": "Support all complication families when possible. Supporting more families means that your complications are available on more watch faces. If you can’t display useful information for a particular complication family, provide an image that represents your app — like your app icon — that still lets people launch your app from the watch face." }, { "type": "paragraph", "text": "Consider creating multiple complications for each family. Supporting multiple complications helps you take advantage of shareable watch faces and lets people configure a watch face that’s centered on an app they love. For example, an app that helps people train for triathlons could offer three circular complications — one for each segment of the race — each of which deep-links to the segment-specific area in the app. This app could also offer a shareable watch face that’s preconfigured to include its swimming, biking, and running complications and to use its custom images and colors. When people choose this watch face, they don’t have to do any configuration before they can start using it. For guidance, see Watch faces." }, { "type": "paragraph", "text": "Define a different deep link for each complication you support. It works well when each complication opens your app to the most relevant area. If all the complications you support open the same area in your app, they can seem less useful." }, { "type": "paragraph", "text": "Keep privacy in mind. With the Always-On Retina display, information on the watch face might be visible to people other than the wearer. Make sure you help people prevent potentially sensitive information from being visible to others. For guidance, see Always On." }, { "type": "paragraph", "text": "Carefully consider when to update data. You provide a complication’s data in the form of a timeline where each entry has a value that specifies the time at which to display your data on the watch face. Different data sets might require different time values. For example, a meeting app might display information about an upcoming meeting an hour before the meeting starts, but a weather app might display forecast information at the time those conditions are expected to occur. You can update the timeline a limited number of times each day, and the system stores a limited number of timeline entries for each app, so you need to choose times that enhance the usefulness of your data. For developer guidance, see Migrating ClockKit complications to WidgetKit." } ] }, { "heading": "Visual design", "level": 2, "content": [ { "type": "paragraph", "text": "Choose a ring or gauge style based on the data you need to display. Many families support a ring or gauge layout that provides consistent ways to represent numerical values that can change over time. For example:" }, { "type": "list", "items": [ "The closed style can convey a value that’s a percentage of a whole, such as for a battery gauge.", "The open style works well when the minimum and maximum values are arbitrary — or don’t represent a percentage of the whole — like for a speed indicator.", "Similar to the open style, the segmented style also displays values within an app-defined range, and can convey rapid value changes, such as in the Noise complication." ] }, { "type": "paragraph", "text": "Make sure images look good in tinted mode. In tinted mode, the system applies a solid color to a complication’s text, gauges, and images, and desaturates full-color images unless you provide tinted versions of them. For developer guidance, see WidgetRenderingMode. (If you’re using legacy templates, tinted mode applies only to graphic complications.) To help your complications perform well in tinted mode:" }, { "type": "list", "items": [ "Avoid using color as the only way to communicate important information. You want people to get the same information in tinted mode as they do in nontinted mode.", "When necessary, provide an alternative tinted-mode version of a full-color image. If your full-color image doesn’t look good when it’s desaturated, you can supply a different version of the image for the system to use in tinted mode." ] }, { "type": "paragraph", "text": "Recognize that people might prefer to use tinted mode for complications, instead of viewing them in full color. When people choose tinted mode, the system automatically desaturates your complication, converting it to grayscale and tinting its images, gauges, and text using a single color that’s based on the wearer’s selected color." }, { "type": "paragraph", "text": "When creating complication content, generally use line widths of two points or greater. Thinner lines can be difficult to see at a glance, especially when the wearer is in motion. Use line weights that suit the size and complexity of the image." }, { "type": "paragraph", "text": "Provide a set of static placeholder images for each complication you support. The system uses placeholder images when there’s no other content to display for your complication’s data. For example, when people first install your app, the system can display a static placeholder while it checks to see if your app can generate a localized placeholder to use instead. Placeholder images can also appear in the carousel from which people select complications. Note that complication image sizes vary per layout (and per legacy template) and the size of a placeholder image may not match the size of the actual image you supply for that complication. For developer guidance, see placeholder(in:)." } ] }, { "heading": "Circular", "level": 2, "content": [ { "type": "paragraph", "text": "Circular layouts can include text, gauges, and full-color images in circular areas on the Infograph and Infograph Modular watch faces. The circular family also defines extra-large layouts for displaying content on the X-Large watch face." }, { "type": "paragraph", "text": "Closed gauge image" }, { "type": "paragraph", "text": "Closed gauge text" }, { "type": "paragraph", "text": "Open gauge image" }, { "type": "paragraph", "text": "Open gauge text" }, { "type": "paragraph", "text": "Open gauge range" }, { "type": "paragraph", "text": "Image" }, { "type": "paragraph", "text": "Stack image" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "You can also add text to accompany a regular-size circular image, using a design that curves the text along the bezel of some watch faces, like Infograph. The text can fill nearly 180 degrees of the bezel before truncating." }, { "type": "paragraph", "text": "Closed gauge image" }, { "type": "paragraph", "text": "As you design images for a regular-size circular complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "40mm", "41mm", "44mm", "45mm/49mm" ], [ "Image", "42x42 pt (84x84 px @2x)", "44.5x44.5 pt (89x89 px @2x)", "47x47 pt (94x94 px @2x)", "50x50 pt (100x100 px @2x)" ], [ "Closed gauge", "27x27 pt (54x54 px @2x)", "28.5x28.5 pt (57x57 px @2x)", "31x31 pt (62x62 px @2x)", "32x32 pt (64x64 px @2x)" ], [ "Open gauge", "11x11 pt (22x22 px @2x)", "11.5x11.5 pt (23x23 px @2x)", "12x12 pt (24x24 px @2x)", "13x13 pt (26x26 px @2x)" ], [ "Stack (not text)", "28x14 pt (56x28 px @2x)", "29.5x15 pt (59X30 px @2x)", "31x16 pt (62x32px @ 2x)", "33.5x16.5 pt (67x33 px @2x)" ] ] }, { "type": "note", "text": "NoteThe system applies a circular mask to each image." }, { "type": "paragraph", "text": "A SwiftUI view that implements a regular-size circular complication uses the following default text values:" }, { "type": "list", "items": [ "Style: Rounded", "Weight: Medium", "Text size: 12 pt (40mm), 12.5 pt (41mm), 13 pt (44mm), 14.5 pt (45mm/49mm)" ] }, { "type": "paragraph", "text": "If you want to design an oversized treatment of important information that can appear on the X-Large watch face — for example, the Contacts complication, which features a contact photo — use the extra-large versions of the circular family’s layouts. The following layouts let you display full-color images, text, and gauges in a large circular region that fills most of the X-Large watch face. Some of the text fields can support multicolor text." }, { "type": "paragraph", "text": "Closed gauge image" }, { "type": "paragraph", "text": "Closed gauge text" }, { "type": "paragraph", "text": "Open gauge image" }, { "type": "paragraph", "text": "Open gauge text" }, { "type": "paragraph", "text": "Open gauge range" }, { "type": "paragraph", "text": "Image" }, { "type": "paragraph", "text": "Stack image" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "Use the following values for guidance as you create images for an extra-large circular complication." }, { "type": "table", "rows": [ [ "Image", "40mm", "41mm", "44mm", "45mm/49mm" ], [ "Image", "120x120 pt (240x240 px @2x)", "127x127 pt (254x254 px @2x)", "132x132 pt (264x264 px @2x)", "143x143 pt (286x286 px @2x)" ], [ "Open gauge", "31x31 pt (62x62 px @2x)", "33x33 pt (66x66 px @2x)", "33x33 pt (66x66 px @2x)", "37x37 pt (74x74 px @2x)" ], [ "Closed gauge", "77x77 pt (154x154 px @2x)", "81.5x81.5 (163x163 px @2x)", "87x87 pt (174x174 px @2x)", "91.5x91.5 (183x183 px @2x)" ], [ "Stack", "80x40 pt (160x80 px @2x)", "85x42 (170x84 px @2x)", "87x44 pt (174x88 px @2x)", "95x48 pt (190x96 px @2x )" ] ] }, { "type": "note", "text": "NoteThe system applies a circular mask to the circular, open-gauge, and closed-gauge images." }, { "type": "paragraph", "text": "Use the following values to create no-content placeholder images for your circular-family complications." }, { "type": "table", "rows": [ [ "Layout", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Circular", "–", "42x42 pt (84x84 px @2x)", "44.5x44.5 pt (89x89 px @2x)", "47x47 pt (94x94 px @2x)", "50x50 pt (100x100 px @2x)" ], [ "Bezel", "–", "42x42 pt (84x84 px @2x)", "44.5x44.5 pt (89x89 px @2x)", "47x47 pt (94x94 px @2x)", "50x50 pt (100x100 px @2x)" ], [ "Extra Large", "–", "120x120 pt (240x240 px @2x)", "127x127 pt (254x254 px @2x)", "132x132 pt (264x264 px @2x)", "143x143 pt (286x286 px @2x)" ] ] }, { "type": "paragraph", "text": "A SwiftUI view that implements an extra-large circular layout uses the following default text values:" }, { "type": "list", "items": [ "Style: Rounded", "Weight: Medium", "Text size: 34.5 pt (40mm), 36.5 pt (41mm), 36.5 pt (44mm), 41 pt (45mm/49mm)" ] } ] }, { "heading": "Corner", "level": 2, "content": [ { "type": "paragraph", "text": "Corner layouts let you display full-color images, text, and gauges in the corners of the watch face, like Infograph. Some of the templates also support multicolor text." }, { "type": "paragraph", "text": "Circular image" }, { "type": "paragraph", "text": "Gauge image" }, { "type": "paragraph", "text": "Gauge text" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "Text image" }, { "type": "paragraph", "text": "As you design images for a corner complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "40mm", "41mm", "44mm", "45mm/49mm" ], [ "Circular", "32x32 pt (64x64 px @2x)", "34x34 pt (68x68 px @2x)", "36x36 pt (72x72 px @2x)", "38x38 pt (76x76 px @2x )" ], [ "Gauge", "20x20 pt (40x40 px @2x)", "21x21 pt (42x42 px @2x)", "22x22 pt (44x44 px @2x)", "24x24 pt (48x48 px @2x)" ], [ "Text", "20x20 pt (40x40 px @2x)", "21x21 pt (42x42 px @2x)", "22x22 pt (44x44 px @2x)", "24x24 pt (48x48 px @2x)" ] ] }, { "type": "note", "text": "NoteThe system applies a circular mask to each image." }, { "type": "paragraph", "text": "Use the following values to create no-content placeholder images for your corner-family complications." }, { "type": "table", "rows": [ [ "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "–", "20x20 pt (40x40 px @2x)", "21x21 pt (42x42 px @2x)", "22x22 pt (44x44 px @2x)", "24x24 pt (48x48 px @2x)" ] ] }, { "type": "paragraph", "text": "A SwiftUI view that implements a corner layout uses the following default text values:" }, { "type": "list", "items": [ "Style: Rounded", "Weight: Semibold", "Text size: 10 pt (40mm), 10.5 pt (41mm), 11 pt (44mm), 12 pt (45mm/49mm)" ] } ] }, { "heading": "Inline", "level": 2, "content": [ { "type": "paragraph", "text": "Inline layouts include utilitarian small and large layouts." }, { "type": "paragraph", "text": "Utilitarian small layouts are intended to occupy a rectangular area in the corner of a watch face, such as the Chronograph and Simple watch faces. The content can include an image, interface icon, or a circular graph." }, { "type": "paragraph", "text": "Flat" }, { "type": "paragraph", "text": "Ring image" }, { "type": "paragraph", "text": "Ring text" }, { "type": "paragraph", "text": "Square" }, { "type": "paragraph", "text": "As you design images for a utilitarian small layout, use the following values for guidance." }, { "type": "table", "rows": [ [ "Content", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Flat", "9-21x9 pt (18-42x18 px @2x)", "10-22x10 pt (20-44x20 px @2x)", "10.5-23.5x21 pt (21-47x21 @2x)", "N/A", "12-26x12 pt (24-52x24 px @2x)" ], [ "Ring", "14x14 pt (28x28 px @2x)", "14x14 pt (28x28 px @2x)", "15x15 pt (30x30 px @2x)", "16x16 pt (32x32 px @2x)", "16.5x16.5 pt (33x33 px @2x)" ], [ "Square", "20x20 pt (40x40 px @2x)", "22x22 pt (44x44 px @2x)", "23.5x23.5 pt (47x47 px @2x)", "25x25 pt (50x50 px @2x)", "26x26 pt (52x52 px @2x)" ] ] }, { "type": "paragraph", "text": "The utilitarian large layout is primarily text-based, but also supports an interface icon placed on the leading side of the text. This layout spans the bottom of a watch face, like the Utility or Motion watch faces." }, { "type": "paragraph", "text": "Large flat" }, { "type": "paragraph", "text": "As you design images for a utilitarian large layout, use the following values for guidance." }, { "type": "table", "rows": [ [ "Content", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Flat", "9-21x9 pt (18-42x18 px @2x)", "10-22x10 pt (20-44x20 px @2x)", "10.5-23.5x10.5 pt (21-47x21 px @2x)", "N/A", "12-26x12 pt (24-52x24 px @2x)" ] ] } ] }, { "heading": "Rectangular", "level": 2, "content": [ { "type": "paragraph", "text": "Rectangular layouts can display full-color images, text, a gauge, and an optional title in a large rectangular region. Some of the text fields can support multicolor text." }, { "type": "paragraph", "text": "The large rectangular region works well for showing details about a value or process that changes over time, because it provides room for information-rich charts, graphs, and diagrams. For example, the Heart Rate complication displays a graph of heart-rate values within a 24-hour period. The graph uses high-contrast white and red for the primary content and a lower-contrast gray for the graph lines and labels, making the data easy to understand at a glance." }, { "type": "paragraph", "text": "Starting with watchOS 10, if you have created a rectangular layout for your watchOS app, the system may display it in the Smart Stack. You can optimize this presentation in a few ways:" }, { "type": "list", "items": [ "By supplying background color or content that communicates information or aids in recognition", "By using intents to specify relevancy, and help ensure that your widget is displayed in the Smart Stack at times that are most appropriate and useful to people", "By creating a custom layout of your information that is optimized for the Smart Stack" ] }, { "type": "paragraph", "text": "For developer guidance, see WidgetFamily.accessoryRectangular. See Widgets for additional guidance on designing widgets for the Smart Stack." }, { "type": "paragraph", "text": "Standard body" }, { "type": "paragraph", "text": "Text gauge" }, { "type": "paragraph", "text": "Large image" }, { "type": "paragraph", "text": "Use the following values for guidance as you create images for a rectangular layout." }, { "type": "table", "rows": [ [ "Content", "40mm", "41mm", "44mm", "45mm/49mm" ], [ "Large image with title *", "150x47 pt (300x94 px @2x)", "159x50 pt (318x100 px @2x)", "171x54 pt (342x108 px @2x)", "178.5x56 pt (357x112 px @2x)" ], [ "Large image without title *", "162x69 pt (324x138 px @2x)", "171.5x73 pt (343x146 px @2x)", "184x78 pt (368x156 px @2x)", "193x82 pt (386x164 px @2x)" ], [ "Standard body", "12x12 pt (24x24 px @2x)", "12.5x12.5 pt (25x25 px @2x)", "13.5x13.5 pt (27x27 px @2x)", "14.5x14.5 pt (29x29 px @2x)" ], [ "Text gauge", "12x12 pt (24x24 px @2x)", "12.5x12.5 pt (25x25 px @2x)", "13.5x13.5 pt (27x27 px @2x)", "14.5x14.5 pt (29x29 px @2x)" ] ] }, { "type": "note", "text": "NoteBoth large-image layouts automatically include a four-point corner radius." }, { "type": "paragraph", "text": "A SwiftUI view that implements a rectangular layout uses the following default text values:" }, { "type": "list", "items": [ "Style: Rounded", "Weight: Medium", "Text size: 16.5 pt (40mm), 17.5 pt (41mm), 18 pt (44mm), 19.5 pt (45mm/49mm)" ] } ] }, { "heading": "Circular small", "level": 3, "content": [ { "type": "paragraph", "text": "Circular small templates display a small image or a few characters of text. They appear in the corner of the watch face (for example, in the Color watch face)." }, { "type": "paragraph", "text": "Ring image" }, { "type": "paragraph", "text": "Ring text" }, { "type": "paragraph", "text": "Simple image" }, { "type": "paragraph", "text": "Simple text" }, { "type": "paragraph", "text": "Stack image" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "As you design images for a circular small complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Ring", "20x20 pt (40x40 px @2x)", "22x22 pt (44x44 px @2x)", "23.5x23.5 pt (47x47 px @2x)", "24x24 pt (48x48 px @2x)", "26x26 pt (52x52 px @2x)" ], [ "Simple", "16x16 pt (32x32 px @2x)", "18x18 pt (36x36 px @2x)", "19x19 pt (38x38 px @2x)", "20x20 pt (40x40 px @2x)", "21.5x21.5 pt (43x43 px @2x)" ], [ "Stack", "16x7 pt (32x14 px @2x)", "17x8 pt (34x16 px @2x)", "18x8.5 pt (36x17 px @2x)", "19x9 pt (38x18 px @2x)", "19x9.5 pt (38x19 px @2x)" ], [ "Placeholder", "16x16 pt (32x32 px @2x)", "18x18x pt (36x36 px @2x)", "19x19 pt (38x38 px @2x)", "20x20 pt (40x40 px @2x)", "21.5x21.5 pt (43x43 px @2x)" ] ] }, { "type": "note", "text": "NoteIn each stack measurement, the width value represents the maximum size." } ] }, { "heading": "Modular small", "level": 3, "content": [ { "type": "paragraph", "text": "Modular small templates display two stacked rows consisting of an icon and content, a circular graph, or a single larger item (for example, the bottom row of complications on the Modular watch face)." }, { "type": "paragraph", "text": "Columns text" }, { "type": "paragraph", "text": "Ring image" }, { "type": "paragraph", "text": "Ring text" }, { "type": "paragraph", "text": "Simple image" }, { "type": "paragraph", "text": "Simple text" }, { "type": "paragraph", "text": "Stack image" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "As you design icons and images for a modular small complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Ring", "18x18 pt (36x36 px @2x)", "19x19 pt (38x38 px @2x)", "20x20 pt (40x40 px @2x)", "21x21 pt (42x42 px @2x)", "22.5x22.5 pt (45x45 px @2x)" ], [ "Simple", "26x26 pt (52x52 px @2x)", "29x29 pt (58x58 px @2x)", "30.5x30.5 pt (61x61 px @2x)", "32x32 pt (64x64 px @2x)", "34.5x34.5 pt (69x69 px @2x)" ], [ "Stack", "26x14 pt (52x28 px @2x)", "29x15 pt (58x30 px @2x)", "30.5x16 pt (61x32 px @2x)", "32x17 pt (64x34 px @2x)", "34.5x18 pt (69x36 px @2x)" ], [ "Placeholder", "26x26 pt (52x52 px @2x)", "29x29 pt (58x58 px @2x)", "30.5x30.5 pt (61x61 px @2x)", "32x32 pt (64x64 px @2x)", "34.5x34.5 pt (69x69 px @2x)" ] ] }, { "type": "note", "text": "NoteIn each stack measurement, the width value represents the maximum size." } ] }, { "heading": "Modular large", "level": 3, "content": [ { "type": "paragraph", "text": "Modular large templates offer a large canvas for displaying up to three rows of content (for example, in the center of the Modular watch face)." }, { "type": "paragraph", "text": "Columns" }, { "type": "paragraph", "text": "Standard body" }, { "type": "paragraph", "text": "Table" }, { "type": "paragraph", "text": "Tall body" }, { "type": "paragraph", "text": "As you design icons and images for a modular large complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Content", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Columns", "11-32x11 pt (22-64x22 px @2x)", "12-37x12 pt (24-74x24 px @2x)", "12.5-39x12.5 pt (25-78x25 px @2x)", "14-42x14 pt (28-84x28 px @2x)", "14.5-44x14.5 pt (29-88x29 px @2x)" ], [ "Standard body", "11-32x11 pt (22-64x22 px @2x)", "12-37x12 pt (24-74x24 px @2x)", "12.5-39x12.5 pt (25-78x25 px @2x)", "14-42x14 pt (28-84x28 px @2x)", "14.5-44x14.5 pt (29-88x29 px @2x)" ], [ "Table", "11-32x11 pt (22-64x22 px @2x)", "12-37x12 pt (24-74x24 px @2x)", "12.5-39x12.5 pt (25-78x25 px @2x)", "14-42x14 pt (28-84x28 px @2x)", "14.5-44x14.5 pt (29-88x29 px @2x)" ] ] } ] }, { "heading": "Extra large", "level": 3, "content": [ { "type": "paragraph", "text": "Extra large templates display larger text and images (for example, on the X-Large watch faces)." }, { "type": "paragraph", "text": "Ring image" }, { "type": "paragraph", "text": "Ring text" }, { "type": "paragraph", "text": "Simple image" }, { "type": "paragraph", "text": "Simple text" }, { "type": "paragraph", "text": "Stack image" }, { "type": "paragraph", "text": "Stack text" }, { "type": "paragraph", "text": "As you design icons and images for an extra large complication, use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "38mm", "40mm/42mm", "41mm", "44mm", "45mm/49mm" ], [ "Ring", "63x63 pt (126x126 px @2x)", "66.5x66.5 pt (133x133 px @2x)", "70.5x70.5 pt (141x141 px @2x)", "73x73 pt (146x146 px @2x)", "79x79 pt (158x158 px @2x)" ], [ "Simple", "91x91 pt (182x182 px @2x)", "101.5x101.5 pt (203x203 px @2x)", "107.5x107.5 pt (215x215 px @2x)", "112x112 pt (224x224 px @2x)", "121x121 pt (242x242 px @2x )" ], [ "Stack", "78x42 pt (156x84 px @2x)", "87x45 pt (174x90 px @2x)", "92x47.5 pt (184x95 px @2x)", "96x51 pt (192x102 px @2x)", "103.5x53.5 pt (207x107 px @2x)" ], [ "Placeholder", "91x91 pt (182x182 px @2x)", "101.5x101.5 pt (203x203 px @2x)", "107.5x107.5 pt (215x215 px @2x)", "112x112 pt (224x224 px @2x)", "121x121 pt (242x242 px @2x)" ] ] }, { "type": "note", "text": "NoteIn each stack measurement, the width value represents the maximum size." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "Not supported in iOS, iPadOS, macOS, tvOS, or visionOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Watch faces" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "WidgetKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "October 24, 2023", "Replaced links to deprecated ClockKit documentation with links to WidgetKit documentation." ], [ "June 5, 2023", "Updated guidance for rectangular complications to support them as widgets in the Smart Stack." ], [ "September 14, 2022", "Added specifications for Apple Watch Ultra." ] ] } ] } ], "platforms": [], "related": [ { "title": "circular", "url": "https://developer.apple.com/design/human-interface-guidelines/complications#Circular" }, { "title": "inline", "url": "https://developer.apple.com/design/human-interface-guidelines/complications#Inline" }, { "title": "legacy templates", "url": "https://developer.apple.com/design/human-interface-guidelines/complications#Legacy-templates" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/complications#Best-practices" }, { "title": "Watch faces", "url": "/design/human-interface-guidelines/watch-faces" }, { "title": "Always On", "url": "/design/human-interface-guidelines/always-on" }, { "title": "Visual design", "url": "/design/human-interface-guidelines/complications#Visual-design" }, { "title": "Circular", "url": "/design/human-interface-guidelines/complications#Circular" }, { "title": "Corner", "url": "/design/human-interface-guidelines/complications#Corner" }, { "title": "Inline", "url": "/design/human-interface-guidelines/complications#Inline" }, { "title": "Rectangular", "url": "/design/human-interface-guidelines/complications#Rectangular" }, { "title": "Widgets", "url": "/design/human-interface-guidelines/widgets" }, { "title": "Legacy templates", "url": "/design/human-interface-guidelines/complications#Legacy-templates" }, { "title": "Circular small", "url": "/design/human-interface-guidelines/complications#Circular-small" }, { "title": "Modular small", "url": "/design/human-interface-guidelines/complications#Modular-small" }, { "title": "Modular large", "url": "/design/human-interface-guidelines/complications#Modular-large" }, { "title": "Extra large", "url": "/design/human-interface-guidelines/complications#Extra-large" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/complications#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/complications#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/complications#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/complications#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/complications#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/complications#Change-log" } ], "image_count": 0 }, { "title": "Dark Mode", "url": "https://developer.apple.com/design/human-interface-guidelines/dark-mode", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "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." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "The Stocks app uses a dark-only appearance" } ] }, { "heading": "Dark Mode colors", "level": 2, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Embrace colors that adapt to the current appearance. Semantic colors (like labelColor and controlColor in macOS or 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." }, { "type": "paragraph", "text": "System colors in the light appearance" }, { "type": "paragraph", "text": "System colors in the dark appearance" }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Icons and images", "level": 3, "content": [ { "type": "paragraph", "text": "The system uses SF Symbols (which automatically adapt to Dark Mode) and full-color images that are optimized for both the light and dark appearances." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Icon in the light appearance with no border" }, { "type": "paragraph", "text": "Icon in the dark appearance with border for better contrast" }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Illustration on a light background" }, { "type": "paragraph", "text": "On a dark background, the same illustration has poor contrast and many details are lost" }, { "type": "paragraph", "text": "Illustration adjusted for better contrast on a dark background" } ] }, { "heading": "Text", "level": 3, "content": [ { "type": "paragraph", "text": "The system uses vibrancy and increased contrast to maintain the legibility of text on darker backgrounds." }, { "type": "paragraph", "text": "Use the system-provided label colors for labels. The primary, secondary, tertiary, and quaternary label colors adapt automatically to the light and dark appearances." }, { "type": "paragraph", "text": "Primary label in the light appearance" }, { "type": "paragraph", "text": "Secondary label in the dark appearance" }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for tvOS. Dark Mode isn’t supported in visionOS or watchOS." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Base" }, { "type": "paragraph", "text": "Elevated" }, { "type": "paragraph", "text": "Light" }, { "type": "paragraph", "text": "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." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Color" }, { "type": "paragraph", "text": "Materials" }, { "type": "paragraph", "text": "Typography" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "August 6, 2024", "Added art contrasting the light and dark appearances." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/dark-mode#Best-practices" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Dark Mode colors", "url": "/design/human-interface-guidelines/dark-mode#Dark-Mode-colors" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/color#Specifications" }, { "title": "Icons and images", "url": "/design/human-interface-guidelines/dark-mode#Icons-and-images" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Text", "url": "/design/human-interface-guidelines/dark-mode#Text" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/dark-mode#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/dark-mode#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/dark-mode#macOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/dark-mode#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/dark-mode#Related" }, { "title": "Materials", "url": "/design/human-interface-guidelines/materials" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Videos", "url": "/design/human-interface-guidelines/dark-mode#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/dark-mode#Change-log" } ], "image_count": 0 }, { "title": "Disclosure controls", "url": "https://developer.apple.com/design/human-interface-guidelines/disclosure-controls", "category": "foundations", "summary": "", "sections": [ { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Use a disclosure control to hide details until they’re relevant. Place controls that people are most likely to use at the top of the disclosure hierarchy so they’re always visible, with more advanced functionality hidden by default. This organization helps people quickly find the most essential information without overwhelming them with too many detailed options." } ] }, { "heading": "Disclosure triangles", "level": 2, "content": [ { "type": "paragraph", "text": "A disclosure triangle shows and hides information and functionality associated with a view or a list of items. For example, Keynote uses a disclosure triangle to show advanced options when exporting a presentation, and the Finder uses disclosure triangles to progressively reveal hierarchy when navigating a folder structure in list view." }, { "type": "paragraph", "text": "A disclosure triangle points inward from the leading edge when its content is hidden and down when its content is visible. Clicking or tapping the disclosure triangle switches between these two states, and the view expands or collapses accordingly to accommodate the content." }, { "type": "paragraph", "text": "Provide a descriptive label when using a disclosure triangle. Make sure your labels indicate what is disclosed or hidden, like “Advanced Options.”" }, { "type": "paragraph", "text": "For developer guidance, see NSButton.BezelStyle.disclosure." } ] }, { "heading": "Disclosure buttons", "level": 2, "content": [ { "type": "paragraph", "text": "A disclosure button shows and hides functionality associated with a specific control. For example, the macOS Save sheet shows a disclosure button next to the Save As text field. When people click or tap this button, the Save dialog expands to give advanced navigation options for selecting an output location for their document." }, { "type": "paragraph", "text": "A disclosure button points down when its content is hidden and up when its content is visible. Clicking or tapping the disclosure button switches between these two states, and the view expands or collapses accordingly to accommodate the content." }, { "type": "paragraph", "text": "Place a disclosure button near the content that it shows and hides. Establish a clear relationship between the control and the expanded choices that appear when a person clicks or taps a button." }, { "type": "paragraph", "text": "Use no more than one disclosure button in a single view. Multiple disclosure buttons add complexity and can be confusing." }, { "type": "paragraph", "text": "For developer guidance, see NSButton.BezelStyle.pushDisclosure." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for macOS. Not supported in tvOS or watchOS." } ] }, { "heading": "iOS, iPadOS, visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "Disclosure controls are available in iOS, iPadOS, and visionOS with the SwiftUI DisclosureGroup view." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Outline views" }, { "type": "paragraph", "text": "Lists and tables" }, { "type": "paragraph", "text": "Buttons" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "DisclosureGroup — SwiftUI" }, { "type": "paragraph", "text": "NSButton.BezelStyle.disclosure — AppKit" }, { "type": "paragraph", "text": "NSButton.BezelStyle.pushDisclosure — AppKit" } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/disclosure-controls#Best-practices" }, { "title": "Disclosure triangles", "url": "/design/human-interface-guidelines/disclosure-controls#Disclosure-triangles" }, { "title": "Disclosure buttons", "url": "/design/human-interface-guidelines/disclosure-controls#Disclosure-buttons" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/disclosure-controls#Platform-considerations" }, { "title": "iOS, iPadOS, visionOS", "url": "/design/human-interface-guidelines/disclosure-controls#iOS-iPadOS-visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/disclosure-controls#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/disclosure-controls#Related" }, { "title": "Outline views", "url": "/design/human-interface-guidelines/outline-views" }, { "title": "Lists and tables", "url": "/design/human-interface-guidelines/lists-and-tables" }, { "title": "Buttons", "url": "/design/human-interface-guidelines/buttons" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/disclosure-controls#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/disclosure-controls#Videos" } ], "image_count": 0 }, { "title": "Foundations", "url": "https://developer.apple.com/design/human-interface-guidelines/foundations", "category": "foundations", "summary": "", "sections": [], "platforms": [], "related": [ { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "App icons", "url": "/design/human-interface-guidelines/app-icons" }, { "title": "Branding", "url": "/design/human-interface-guidelines/branding" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Dark Mode", "url": "/design/human-interface-guidelines/dark-mode" }, { "title": "Icons", "url": "/design/human-interface-guidelines/icons" }, { "title": "Images", "url": "/design/human-interface-guidelines/images" }, { "title": "Immersive experiences", "url": "/design/human-interface-guidelines/immersive-experiences" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Materials", "url": "/design/human-interface-guidelines/materials" }, { "title": "Motion", "url": "/design/human-interface-guidelines/motion" }, { "title": "Privacy", "url": "/design/human-interface-guidelines/privacy" }, { "title": "Right to left", "url": "/design/human-interface-guidelines/right-to-left" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Spatial layout", "url": "/design/human-interface-guidelines/spatial-layout" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Writing", "url": "/design/human-interface-guidelines/writing" } ], "image_count": 0 }, { "title": "Icons", "url": "https://developer.apple.com/design/human-interface-guidelines/icons", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Apps and games use a variety of simple icons to help people understand the items, actions, and modes they can choose. Unlike 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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "To help achieve visual consistency, adjust individual icon sizes as necessary…" }, { "type": "paragraph", "text": "…and use the same stroke weight in every icon." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "An asymmetric icon can look off center even though it’s not." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Moving the icon a few pixels higher optically centers it; including the pixels in padding simplifies centering." }, { "type": "paragraph", "text": "Adjustments for optical centering are typically very small, but they can have a big impact on your app’s appearance." }, { "type": "paragraph", "text": "Before optical centering (left) and after optical centering (right)." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "In a toolbar, a selected icon receives the app’s accent color." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Create localized versions of an icon that displays individual characters." }, { "type": "paragraph", "text": "Create a flipped version of an icon that suggests reading direction." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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 or the SF Symbols that represent various Apple products." } ] }, { "heading": "Standard icons", "level": 2, "content": [ { "type": "paragraph", "text": "For icons to represent common actions in menus, toolbars, buttons, and other places in interfaces across Apple platforms, you can use these SF Symbols." } ] }, { "heading": "Editing", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Cut", "", "scissors" ], [ "Copy", "", "document.on.document" ], [ "Paste", "", "document.on.clipboard" ], [ "Done", "", "checkmark" ], [ "Save" ], [ "Cancel", "", "xmark" ], [ "Close" ], [ "Delete", "", "trash" ], [ "Undo", "", "arrow.uturn.backward" ], [ "Redo", "", "arrow.uturn.forward" ], [ "Compose", "", "square.and.pencil" ], [ "Duplicate", "", "plus.square.on.square" ], [ "Rename", "", "pencil" ], [ "Move to", "", "folder" ], [ "Folder" ], [ "Attach", "", "paperclip" ], [ "Add", "", "plus" ], [ "More", "", "ellipsis" ] ] } ] }, { "heading": "Selection", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Select", "", "checkmark.circle" ], [ "Deselect", "", "xmark" ], [ "Close" ], [ "Delete", "", "trash" ] ] } ] }, { "heading": "Text formatting", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Superscript", "", "textformat.superscript" ], [ "Subscript", "", "textformat.subscript" ], [ "Bold", "", "bold" ], [ "Italic", "", "italic" ], [ "Underline", "", "underline" ], [ "​​Align Left", "", "text.alignleft" ], [ "Center", "", "text.aligncenter" ], [ "Justified", "", "text.justify" ], [ "Align Right", "", "text.alignright" ] ] } ] }, { "heading": "Search", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Search", "", "magnifyingglass" ], [ "Find", "", "text.page.badge.magnifyingglass" ], [ "Find and Replace" ], [ "Find Next" ], [ "Find Previous" ], [ "Use Selection for Find" ], [ "Filter", "", "line.3.horizontal.decrease" ] ] } ] }, { "heading": "Sharing and exporting", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Share", "", "square.and.arrow.up" ], [ "Export" ], [ "Print", "", "printer" ] ] } ] }, { "heading": "Users and accounts", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Account", "", "person.crop.circle" ], [ "User" ], [ "Profile" ] ] } ] }, { "heading": "Ratings", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Dislike", "", "hand.thumbsdown" ], [ "Like", "", "hand.thumbsup" ] ] } ] }, { "heading": "Layer ordering", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Bring to Front", "", "square.3.layers.3d.top.filled" ], [ "Send to Back", "", "square.3.layers.3d.bottom.filled" ], [ "Bring Forward", "", "square.2.layers.3d.top.filled" ], [ "Send Backward", "", "square.2.layers.3d.bottom.filled" ] ] } ] }, { "heading": "Other", "level": 3, "content": [ { "type": "table", "rows": [ [ "Action", "Icon", "Symbol name" ], [ "Alarm", "", "alarm" ], [ "Archive", "", "archivebox" ], [ "Calendar", "", "calendar" ] ] } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Document icons", "level": 4, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Background fill" }, { "type": "paragraph", "text": "Center image" }, { "type": "paragraph", "text": "Text" }, { "type": "paragraph", "text": "macOS composites the elements you supply to produce your custom document icon." }, { "type": "paragraph", "text": "Apple Design Resources 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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "The 32x32 px icon has fewer grid lines and a thicker EKG line." }, { "type": "paragraph", "text": "The 16x16 px @2x icon retains the EKG line but has no grid lines." }, { "type": "paragraph", "text": "The 16x16 px @1x icon has no EKG line and no grid lines." }, { "type": "paragraph", "text": "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." }, { "type": "list", "items": [ "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" ] }, { "type": "paragraph", "text": "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:" }, { "type": "list", "items": [ "256x256 px @1x, 512x512 px @2x", "128x128 px @1x, 256x256 px @2x", "32x32 px @1x, 64x64 px @2x", "16x16 px @1x, 32x32 px @2x" ] }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "App icons" }, { "type": "paragraph", "text": "SF Symbols" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added a table of SF Symbols that represent common actions." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "app icons", "url": "/design/human-interface-guidelines/app-icons" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/icons#Best-practices" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Right to left", "url": "/design/human-interface-guidelines/right-to-left" }, { "title": "VoiceOver", "url": "/design/human-interface-guidelines/voiceover" }, { "title": "Standard icons", "url": "/design/human-interface-guidelines/icons#Standard-icons" }, { "title": "menus", "url": "/design/human-interface-guidelines/menus" }, { "title": "toolbars", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "buttons", "url": "/design/human-interface-guidelines/buttons" }, { "title": "Editing", "url": "/design/human-interface-guidelines/icons#Editing" }, { "title": "Selection", "url": "/design/human-interface-guidelines/icons#Selection" }, { "title": "Text formatting", "url": "/design/human-interface-guidelines/icons#Text-formatting" }, { "title": "Search", "url": "/design/human-interface-guidelines/icons#Search" }, { "title": "Sharing and exporting", "url": "/design/human-interface-guidelines/icons#Sharing-and-exporting" }, { "title": "Users and accounts", "url": "/design/human-interface-guidelines/icons#Users-and-accounts" }, { "title": "Ratings", "url": "/design/human-interface-guidelines/icons#Ratings" }, { "title": "Layer ordering", "url": "/design/human-interface-guidelines/icons#Layer-ordering" }, { "title": "Other", "url": "/design/human-interface-guidelines/icons#Other" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/icons#Platform-considerations" }, { "title": "macOS", "url": "/design/human-interface-guidelines/icons#macOS" }, { "title": "Document icons", "url": "/design/human-interface-guidelines/icons#Document-icons" }, { "title": "Resources", "url": "/design/human-interface-guidelines/icons#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/icons#Related" }, { "title": "Videos", "url": "/design/human-interface-guidelines/icons#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/icons#Change-log" } ], "image_count": 0 }, { "title": "Images", "url": "https://developer.apple.com/design/human-interface-guidelines/images", "category": "foundations", "summary": "", "sections": [ { "heading": "Resolution", "level": 2, "content": [ { "type": "paragraph", "text": "Different devices can display images at different resolutions. For example, a 2D device displays images according to the resolution of its screen." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "1x (10x10 px)" }, { "type": "paragraph", "text": "2x (20x20 px)" }, { "type": "paragraph", "text": "3x (30x30 px)" }, { "type": "paragraph", "text": "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." }, { "type": "table", "rows": [ [ "Platform", "Scale factors" ], [ "iPadOS, watchOS", "@2x" ], [ "iOS", "@2x and @3x" ], [ "visionOS", "@2x or higher (see visionOS)" ], [ "macOS, tvOS", "@1x and @2x" ] ] }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Formats", "level": 2, "content": [ { "type": "paragraph", "text": "As you create different types of images, consider the following recommendations." }, { "type": "table", "rows": [ [ "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" ] ] } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, or macOS." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "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." } ] }, { "heading": "Parallax effect", "level": 4, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Layered images are required to support the parallax effect." } ] }, { "heading": "Layered images", "level": 4, "content": [ { "type": "paragraph", "text": "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." }, { "type": "important", "text": "ImportantYour tvOS app icon must use a layered image. For other focusable images in your app, including Top Shelf images, layered images are strongly encouraged, but optional." }, { "type": "paragraph", "text": "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." }, { "type": "note", "text": "Developer noteIf 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." }, { "type": "paragraph", "text": "Use standard interface elements to display layered images. If you use standard views and system-provided focus APIs — such as FocusState — layered images automatically get the parallax treatment when people bring them into focus." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "Generally, keep text in the foreground. Unless you want to obscure text, bring it to the foreground layer for clarity." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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 for developer guidance." }, { "type": "paragraph", "text": "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)." } ] }, { "heading": "Spatial photos and spatial scenes", "level": 4, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "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." }, { "type": "paragraph", "text": "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:" }, { "type": "table", "rows": [ [ "Screen size", "Image scale" ], [ "38mm", "90%" ], [ "40mm", "100%" ], [ "41mm", "106%" ], [ "42mm", "100%" ], [ "44mm", "110%" ], [ "45mm", "119%" ], [ "49mm", "119%" ] ] } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Design Resources" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Drawing sharp layer-based content in visionOS — visionOS" }, { "type": "paragraph", "text": "Images — SwiftUI" }, { "type": "paragraph", "text": "UIImageView — UIKit" }, { "type": "paragraph", "text": "NSImageView — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "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." ] ] } ] } ], "platforms": [], "related": [ { "title": "Resolution", "url": "/design/human-interface-guidelines/images#Resolution" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/images#visionOS" }, { "title": "Formats", "url": "/design/human-interface-guidelines/images#Formats" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/images#Best-practices" }, { "title": "Color management", "url": "/design/human-interface-guidelines/color#Color-management" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/images#Platform-considerations" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/images#tvOS" }, { "title": "Parallax effect", "url": "/design/human-interface-guidelines/images#Parallax-effect" }, { "title": "Layered images", "url": "/design/human-interface-guidelines/images#Layered-images" }, { "title": "app icon", "url": "/design/human-interface-guidelines/app-icons#tvOS" }, { "title": "Top Shelf", "url": "/design/human-interface-guidelines/top-shelf" }, { "title": "App icons", "url": "/design/human-interface-guidelines/app-icons" }, { "title": "Layer design", "url": "/design/human-interface-guidelines/app-icons#Layer-design" }, { "title": "Spatial photos and spatial scenes", "url": "/design/human-interface-guidelines/images#Spatial-photos-and-spatial-scenes" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/images#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/images#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/images#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/images#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/images#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/images#Change-log" } ], "image_count": 0 }, { "title": "Immersive experiences", "url": "https://developer.apple.com/design/human-interface-guidelines/immersive-experiences", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "You can choose whether your visionOS app or game launches in the Shared Space or in a Full Space. In the Shared Space, your software runs alongside other experiences, and people can switch between them much as they do on a Mac; in a Full Space, your app or game runs alone, hiding other experiences and helping people immerse themselves in your content. Apps and games can support different types of immersion, and can transition fluidly between the Shared Space and a Full Space at any time." } ] }, { "heading": "Immersion and passthrough", "level": 2, "content": [ { "type": "paragraph", "text": "In visionOS, people use passthrough to see their physical surroundings. Passthrough provides real-time video from the device’s external cameras, helping people feel comfortable and connected to their physical context." }, { "type": "paragraph", "text": "People can also use the Digital Crown at any time to manage app or game content or adjust passthrough. For example, people can press and hold the Digital Crown to recenter content in their field of view or double-click it to briefly hide all content and show passthrough for a clear view of their surroundings." }, { "type": "paragraph", "text": "The system also helps people remain comfortable by automatically changing the opacity of content in certain situations. For example, if someone gets too close to a physical object in mixed immersion, the content in front of them dims briefly so they can see their immediate physical surroundings more clearly. In more immersive experiences — such as in the progressive and full styles described below — the system defines a boundary that extends about 1.5 meters from the initial position of the wearer’s head. As their head gets close to this boundary, the entire experience begins to fade and passthrough increases. When their head moves beyond this boundary, the immersive visuals are replaced in space by the app’s icon, and are restored when the wearer returns to their original location or recenters their view using the Digital Crown." } ] }, { "heading": "Immersion styles", "level": 3, "content": [ { "type": "paragraph", "text": "When your app or game transitions to a Full Space, the system hides other apps so people can focus on yours. In a Full Space, you can display 3D content that isn’t bound by a window, in addition to content in standard windows and volumes. For developer guidance, see automatic." }, { "type": "paragraph", "text": "visionOS offers several ways to immerse people in your content in the Shared Space as well as when you transition to a Full Space. For example, you can:" }, { "type": "list", "items": [ "Use dimmed passthrough to bring attention to your content. You can subtly dim or tint passthrough and other visible content to bring attention to your app in the Shared Space without hiding other apps and games, or create a more focused experience in a Full Space. While passthrough is tinted black by default, you can apply a custom tint color to create a dynamic experience in your app. For developer guidance, see SurroundingsEffect." ] }, { "type": "list", "items": [ "Create unbounded 3D experiences. Use the mixed immersion style in a Full Space to blend your content with passthrough. When your app or game runs in a Full Space, you can request access to information about nearby physical objects and room layout, helping you display virtual content in a person’s surroundings. The mixed immersion style doesn’t define a boundary. Instead, when a person gets too close to a physical object, the system automatically makes nearby content semi-opaque to help them remain aware of their surroundings. For developer guidance, see mixed and ARKit.", "Use progressive immersion to blend your custom environment with a person’s surroundings. You can use the progressive style in a Full Space to display a custom environment that partially replaces passthrough. You can also define a specific range of immersion that works best with your app or game, and display content in portrait or landscape orientation. While in your immersive experience, people can use the Digital Crown to adjust the amount of immersion within either the default range of 120- to 360-degrees or a custom range, if you specify one. The system automatically defines an approximately 1.5-meter boundary when an experience transitions to the progressive style. For developer guidance, see progressive." ] }, { "type": "list", "items": [ "Use full immersion to create a fully immersive experience. You can use the full style in a Full Space to display a 360-degree custom environment that completely replaces passthrough and transports people to a new place. As with the progressive style, the system defines an approximately 1.5-meter boundary when a fully immersive experience starts. For developer guidance, see full." ] }, { "type": "paragraph", "text": "Mixed immersion style in a Full Space blending in-app objects with real-world surroundings" }, { "type": "paragraph", "text": "Progressive immersion style in a Full Space blending the app’s custom environment with real-world surroundings" }, { "type": "paragraph", "text": "Full immersion style in a Full Space showing a 360-degree custom environment" } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Offer multiple ways to use your app or game. In addition to giving people the freedom to choose their experiences, it’s essential to design your software to support the accessibility features people use to personalize the ways they interact with their devices. For guidance, see Accessibility." }, { "type": "paragraph", "text": "Prefer launching your app or game in the Shared Space or using the mixed immersion style. Launching in the Shared Space lets people reference your app or game while using other running software, and enables seamless switching between them. If your app or game provides a fully immersive or progressive style experience, launching in the mixed immersion style or with a window-based experience in the Shared Space gives people more control, letting them choose when to increase immersion." }, { "type": "paragraph", "text": "Reserve immersion for meaningful moments and content. Not every task benefits from immersion, and not every immersive task needs to be fully immersive. Although people sometimes want to enter a different world, they often want to stay grounded in their surroundings while they’re using your app or game, and they can appreciate being able to use other software and system features at the same time. Instead of assuming that your app or game needs to be fully immersive most of the time, design ways for people to immerse themselves in the individual tasks and content that make your experience unique. For example, people can browse their albums in Photos using a familiar app window in the Shared Space, but when they want to examine a single photo, they can temporarily transition to a more immersive experience in a Full Space where they can expand the photo and appreciate its details." }, { "type": "paragraph", "text": "Help people engage with key moments in your app or game, regardless of the level of immersion. Cues like dimming, tinting, motion, scale, and Spatial Audio can help draw people’s attention to a specific area of content, whether it’s in a window in the Shared Space or in a completely immersive experience in a Full Space. Start with subtle cues that gently guide people’s attention, strengthening the cues only when there’s a good reason to do so." }, { "type": "paragraph", "text": "Prefer subtle tint colors for passthrough. In visionOS 2 and later, you can tint passthrough to help a person’s surroundings visually coordinate with your content, while also making their hands look like they belong in your experience. Avoid bright or dramatic tints that can distract people and diminish the sense of immersion. For developer guidance, see SurroundingsEffect." } ] }, { "heading": "Promoting comfort", "level": 2, "content": [ { "type": "paragraph", "text": "Be mindful of people’s visual comfort. For example, although you can place 3D content anywhere while your app or game is running in a Full Space, prefer placing it within people’s field of view. Also, make sure you display motion in comfortable ways while your software runs in a Full Space to avoid causing distraction, confusion, or discomfort. For guidance, see Motion." }, { "type": "paragraph", "text": "Choose a style of immersion that supports the movements people might make while they’re in your app or game. It’s essential to choose the right style for your immersive experience because it allows the system to respond appropriately when people move. Although people can make minor physical movements while in an immersive experience — such as shifting their weight, turning around, or switching between sitting and standing — making excessive movements can cause the system to interrupt some experiences. In particular, avoid using the progressive or full immersion styles or transition back to the mixed immersion style if you think people might need to move beyond the 1.5-meter boundary." }, { "type": "paragraph", "text": "Avoid encouraging people to move while they’re in a progressive or fully immersive experience. Some people may not want to move, or are unable to move because of a disability or their physical surroundings. Design ways for people to interact with content without moving. For example, let people bring a virtual object closer to them instead of expecting them to move closer to the object." }, { "type": "paragraph", "text": "If you use the mixed immersion style, avoid obscuring passthrough too much. People use passthrough to help them understand and navigate their physical surroundings, so it’s important to avoid displaying virtual objects that block too much of their view. If your app or game displays virtual objects that could substantially obscure passthrough, use the full or progressive immersion styles instead of mixed." }, { "type": "paragraph", "text": "Adopt ARKit if you want to blend custom content with someone’s surroundings. For example, you might want to integrate virtual content into someone’s surroundings or use the wearer’s hand positions to inform your experience. If you need access to these types of sensitive data, you must request people’s permission. For guidance, see Privacy; for developer guidance, see SceneReconstructionProvider." } ] }, { "heading": "Transitioning between immersive styles", "level": 2, "content": [ { "type": "paragraph", "text": "Design smooth, predictable transitions when changing immersion. Help people prepare for different experiences by providing gentle transitions that let people visually track changes. Avoid sudden, jarring transitions that might be disorienting or uncomfortable. For developer guidance, see CoordinateSpaceProtocol." }, { "type": "paragraph", "text": "Let people choose when to enter or exit a more immersive experience. It can be disorienting for someone to suddenly enter a more immersive experience when they’re not expecting it. Instead, provide a clear action to enter or exit immersion so people can decide when to be more immersed in your content, and when to leave. For example, Keynote provides a prominent Exit button in its fully immersive Rehearsal environment to help people return to the slide-viewing window. Avoid requiring people to use system controls to reduce immersion in your experience." }, { "type": "paragraph", "text": "Indicate the purpose of an exit control. Make sure your button clarifies whether it returns people to a previous, less immersive context or quits an experience altogether. If exiting your immersive experience also quits your app or game, consider providing controls that let people pause or return to a place where they can save their progress before quitting." } ] }, { "heading": "Displaying virtual hands", "level": 2, "content": [ { "type": "paragraph", "text": "When your immersive app or game transitions to a Full Space, it can ask permission to hide a person’s hands and instead show virtual hands that represent them." }, { "type": "paragraph", "text": "Prefer virtual hands that match familiar characteristics. For example, match the positions and gestures of the viewer’s hands so they can continue to interact with your app or game in ways that feel natural. Hands that work in familiar ways help people stay immersed in the experience when in fully virtual worlds." }, { "type": "paragraph", "text": "Use caution if you create virtual hands that are larger than the viewer’s hands. Virtual hands that are significantly bigger than human hands can prevent people from seeing the content they’re interested in and can make interactions feel clumsy. Also, large virtual hands can seem out of proportion with the space, appearing to be too close to the viewer’s face." }, { "type": "paragraph", "text": "If there’s an interruption in hand-tracking data, fade out virtual hands and reveal the viewer’s own hands. Don’t let the virtual hands become unresponsive and appear frozen. When hand-tracking data returns, fade the virtual hands back in." } ] }, { "heading": "Creating an environment", "level": 2, "content": [ { "type": "paragraph", "text": "When your app or game transitions to a Full Space, you can replace passthrough with a custom environment that partially or completely surrounds a person, transporting them to a new place. The following guidelines can help you design a beautiful environment that people appreciate." }, { "type": "paragraph", "text": "Minimize distracting content. To help immerse people in a primary task like watching a video, avoid displaying a lot of movement or high-contrast details in your environment. Alternatively, when you want to draw people’s attention to certain areas of your environment, consider techniques like using the highest quality textures and shapes in the important area while using lower quality assets and dimming in less important areas." }, { "type": "paragraph", "text": "Help people distinguish interactive objects in your environment. People often use an object’s proximity to help them decide if they can interact with it. For example, when you place a 3D object far away from people, they often don’t try to touch or move toward it, but when you place a 3D object close to people, they’re more likely to try interacting with it." }, { "type": "paragraph", "text": "Keep animation subtle. Small, gentle movements, like clouds drifting or transforming, can enrich your custom environment without distracting people or making them uncomfortable. Always avoid displaying too much movement near the edges of a person’s field of view. For guidance, see Motion." }, { "type": "paragraph", "text": "Create an expansive environment, regardless of the place it depicts. A small, restrictive environment can make people feel uncomfortable and even claustrophobic." }, { "type": "paragraph", "text": "Use Spatial Audio to create atmosphere. In visionOS, you use Spatial Audio to play sound that people can perceive as coming from specific locations in space, not just from speakers (for guidance, see Playing audio). As you design a soundscape that enhances your custom environment, keep the experience fresh and captivating by avoiding too much repetition or looping. If people can play other audio while they’re in your environment — for example, while watching a movie — be sure to lower the volume of the soundscape or stop it completely." }, { "type": "paragraph", "text": "In general, avoid using a flat 360-degree image to create your environment. A 360-degree image doesn’t tend to give people a sense of scale when they view it in an environment, so it can reduce the immersiveness of the experience. Prefer creating object meshes that include lighting, and use shaders to implement subtle animations like the movements of clouds or leaves or the reflections of objects." }, { "type": "paragraph", "text": "Help people feel grounded. Always provide a ground plane mesh so people don’t feel like they’re floating. If you must use a flat 360-degree image in your environment, adding a ground plane mesh can help it feel more realistic." }, { "type": "paragraph", "text": "Minimize asset redundancy. Using the same assets or models too frequently tends to make an environment feel less realistic." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "Not supported in iOS, iPadOS, macOS, tvOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Spatial layout" }, { "type": "paragraph", "text": "Motion" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Creating fully immersive experiences in your app — visionOS" }, { "type": "paragraph", "text": "Incorporating real-world surroundings in an immersive experience — visionOS" }, { "type": "paragraph", "text": "ImmersionStyle — visionOS" }, { "type": "paragraph", "text": "Immersive spaces — SwiftUI" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Clarified guidance and noted the availability of portrait-oriented progressive immersion." ], [ "November 19, 2024", "Refined immersion style guidance and added artwork." ], [ "June 10, 2024", "Added guidance for tinting passthrough and specifying initial, minimum, and maximum immersion levels." ], [ "May 7, 2024", "Added guidance for creating an environment." ], [ "February 2, 2024", "Clarified guidance for choosing an immersion style that matches the experience your app provides." ], [ "October 24, 2023", "Updated artwork." ], [ "June 21, 2023", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Immersion and passthrough", "url": "/design/human-interface-guidelines/immersive-experiences#Immersion-and-passthrough" }, { "title": "Digital Crown", "url": "/design/human-interface-guidelines/digital-crown" }, { "title": "Immersion styles", "url": "/design/human-interface-guidelines/immersive-experiences#Immersion-styles" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/immersive-experiences#Best-practices" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "motion", "url": "/design/human-interface-guidelines/motion" }, { "title": "scale", "url": "/design/human-interface-guidelines/spatial-layout#Scale" }, { "title": "Spatial Audio", "url": "/design/human-interface-guidelines/playing-audio#visionOS" }, { "title": "Promoting comfort", "url": "/design/human-interface-guidelines/immersive-experiences#Promoting-comfort" }, { "title": "field of view", "url": "/design/human-interface-guidelines/spatial-layout#Field-of-view" }, { "title": "Privacy", "url": "/design/human-interface-guidelines/privacy" }, { "title": "Transitioning between immersive styles", "url": "/design/human-interface-guidelines/immersive-experiences#Transitioning-between-immersive-styles" }, { "title": "Displaying virtual hands", "url": "/design/human-interface-guidelines/immersive-experiences#Displaying-virtual-hands" }, { "title": "Creating an environment", "url": "/design/human-interface-guidelines/immersive-experiences#Creating-an-environment" }, { "title": "Playing audio", "url": "/design/human-interface-guidelines/playing-audio" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/immersive-experiences#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/immersive-experiences#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/immersive-experiences#Related" }, { "title": "Spatial layout", "url": "/design/human-interface-guidelines/spatial-layout" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/immersive-experiences#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/immersive-experiences#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/immersive-experiences#Change-log" } ], "image_count": 0 }, { "title": "Inclusion", "url": "https://developer.apple.com/design/human-interface-guidelines/inclusion", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "To help you design an inclusive app or game, consider the following goals as you review the words and images you use and the experiences you offer." }, { "type": "paragraph", "text": "As with all design, designing an inclusive app is an iterative process that takes time to get right. Throughout the process, be prepared to examine your assumptions about how other people think and feel and be open to evolving knowledge and understanding." } ] }, { "heading": "Inclusive by design", "level": 2, "content": [ { "type": "paragraph", "text": "Simple, intuitive experiences are at the core of well-designed apps and games. To design an intuitive experience, you start by investigating people’s goals and perspectives so you can present content that resonates with them." }, { "type": "paragraph", "text": "Empathy is an important tool in this investigation because it helps you understand how people with different perspectives might respond to the content and experiences you create. For example, you might discover that from some perspectives a word or image is incomprehensible or has a meaning you don’t intend." }, { "type": "paragraph", "text": "Although each person’s perspective comprises a unique intersection of human qualities that’s both distinct and dynamic, all perspectives arise from human characteristics and experiences that everyone shares, including:" }, { "type": "list", "items": [ "Age", "Gender and gender identity", "Race and ethnicity", "Sexuality", "Physical attributes", "Cognitive attributes", "Permanent, temporary, and situational disabilities", "Language and culture", "Religion", "Education", "Political or philosophical opinions", "Social and economic context" ] }, { "type": "paragraph", "text": "As you examine your app or game through different perspectives, avoid framing the work as merely a search for content that might give offense. Although no design should contain offensive material or experiences, an inoffensive app or game isn’t necessarily an inclusive one. Focusing on inclusion can help you avoid potentially offensive content while also helping you create a welcoming experience that everyone can enjoy." } ] }, { "heading": "Welcoming language", "level": 2, "content": [ { "type": "paragraph", "text": "Using plain, inclusive language welcomes everyone and helps them understand your app or game. Carefully review the writing in your experience to make sure that your tone and words don’t exclude people. Here are a few tips for writing text — also known as copy — that’s direct, easy to understand, and inclusive." }, { "type": "paragraph", "text": "Consider the tone of your copy from different perspectives. The style of your writing communicates almost as much as the words you use. Although different apps use different communication styles, make sure the tone you use doesn’t send messages you don’t intend. For example, an academic tone can make an app or game seem like it welcomes only high levels of education. As you seek the style that’s right for your experience, be clear, direct, and respectful." }, { "type": "paragraph", "text": "Pay attention to how you refer to people. It typically works well to use you and your to address people directly. Referring to people indirectly as the user or the player can make your experience feel distant and unwelcoming. Also, consider reserving words like we and our to represent your software or company; otherwise, these terms can suggest a personal relationship with people that might be interpreted as insulting or condescending." }, { "type": "paragraph", "text": "Avoid using specialized or technical terms without defining them. Using specialized or technical terms can make your writing more succinct, but doing so excludes people who don’t know what the terms mean. If you must use such terms, be sure to define them first and make the definitions easy for people to look up. Even when people know the definition of a specialized or technical term in a sentence, the sentence is easier to read — and translate — when it uses plain language instead." }, { "type": "paragraph", "text": "Replace colloquial expressions with plain language. Colloquial expressions are often culture-specific and can be difficult to translate. Worse, some colloquial phrases have exclusionary meanings you might not know. For example, the phrases peanut gallery and grandfathered in both arose from oppressive contexts and continue to exclude people. Even when a colloquial phrase doesn’t have an exclusionary meaning, it can still exclude everyone who doesn’t understand it." }, { "type": "paragraph", "text": "Consider carefully before including humor. Humor is highly subjective and — similar to colloquial expressions — difficult to translate from one culture to another. Including humor in your experience risks confusing people who donʼt understand it, irritating people who tire of repeatedly encountering it, and insulting people who interpret it differently. For additional writing guidance, see Writing inclusively." } ] }, { "heading": "Being approachable", "level": 2, "content": [ { "type": "paragraph", "text": "An approachable app or game doesn’t require people to have particular skills or knowledge before they can use it, and it gives people a clear path toward deepening their understanding over time. Here are two ways to help make an experience approachable." }, { "type": "list", "items": [ "Present a clear, straightforward interface. To help you design a simple interface that fits in with other experiences on each platform, see Designing for iOS, Designing for iPadOS, Designing for macOS, Designing for tvOS, Designing for visionOS, Designing for watchOS, and Designing for games.", "Build in ways to learn how to use your app or game. Consider designing an onboarding flow that helps people who are new to your experience take a step-by-step approach while letting others skip straight to the content they want. For guidance, see Onboarding." ] } ] }, { "heading": "Gender identity", "level": 2, "content": [ { "type": "paragraph", "text": "Throughout history, cultures around the world have recognized a spectrum of self-identity and expression that expands beyond the binary variants of woman and man." }, { "type": "paragraph", "text": "You can help everyone feel welcome in your app or game by avoiding unnecessary references to specific genders. For example, a recipe-sharing app that uses copy like “You can let a subscriber post his or her recipes to your shared folder” could avoid unnecessary gender references by using an alternative like “Subscribers can post recipes to your shared folder.” In addition to using the gender-neutral noun “subscribers,” the revised copy avoids the unnecessary singular pronouns “his” and “her,” helping the sentence remain inclusive when it’s localized for languages that use gendered pronouns." }, { "type": "paragraph", "text": "In addition, you can often avoid referencing a specific gender in an avatar, emoji, glyph, or game character. To welcome everyone to your app or game, prefer giving people the tools they need to customize such items as they choose." }, { "type": "paragraph", "text": "If you need to depict a generic person or people, use a nongendered human image to reinforce the message that generic person means human, not man or woman. SF Symbols provides many nongendered glyphs you can use, such as the figure and person symbols shown here:" }, { "type": "paragraph", "text": "person.crop.circle" }, { "type": "paragraph", "text": "person.3.fill" }, { "type": "paragraph", "text": "figure.wave" }, { "type": "paragraph", "text": "Most apps and games don’t need to know a person’s gender, but if you require this information — such as for health or legal reasons — consider providing inclusive options, such as nonbinary, self-identify, and decline to state. In this situation, you could also let people specify the pronouns they use so you can address them properly when necessary." } ] }, { "heading": "People and settings", "level": 2, "content": [ { "type": "paragraph", "text": "Portraying human diversity is one of the most noticeable ways your app or game can welcome everyone. When people recognize others like themselves within an experience and its related materials, they’re less likely to feel excluded and can be more likely to think they’ll benefit from it." }, { "type": "paragraph", "text": "As you create copy and images that represent people, portray a range of human characteristics and activities. For example, a fitness app could feature exercise moves demonstrated by people with different racial backgrounds, body types, ages, and physical capabilities. If you need to depict occupations or behaviors, avoid stereotypical representations, such as showing only male doctors, female nurses, or heroes and villains that may perpetuate real-world racial or gender stereotypes." }, { "type": "paragraph", "text": "Also review the settings and objects you show. For example, showing high levels of affluence might make sense in some scenarios, but in other cases it can be unwelcoming and make an experience seem out of touch. When it makes sense in your app or game, prefer showing places, homes, activities, and items that are familiar and relatable to most people." } ] }, { "heading": "Avoiding stereotypes", "level": 2, "content": [ { "type": "paragraph", "text": "Everyone holds biases and stereotypes — often unconsciously — and it can be challenging to discover how they affect your thoughts. A goal of inclusive design is to become aware of your biases and generalizations so you can recognize where they might influence your design decisions." }, { "type": "paragraph", "text": "For example, consider an app that helps people manage account access for various family members. If this app uses a stereotypical definition of family — such as a woman, a man, and their biological children — it’s likely to communicate this perspective in its copy and images. Because the app assumes that people’s families fit this narrow definition, it excludes everyone whose family is different." }, { "type": "paragraph", "text": "Although the assumption made in the account-access app might seem like an obvious mistake, it’s important to realize that not all assumptions are so easy to spot. For example, consider an app or game that requires people to choose security questions they can answer for future identity confirmation, such as:" }, { "type": "list", "items": [ "What was your favorite subject in college?", "What was the make of your first car?", "How did you feel when you first saw a rainbow?" ] }, { "type": "paragraph", "text": "From some perspectives these questions refer to commonplace events, but all are based on experiences that not everyone has. Using a context-specific experience to communicate something is useless for everyone who doesn’t share that context and effectively excludes them. To create alternatives to the culture- and capability-specific questions above, you might reference more universal human experiences like:" }, { "type": "list", "items": [ "What’s your favorite activity?", "What was the name of your first friend?", "What quality describes you best?" ] }, { "type": "paragraph", "text": "Basing design decisions on stereotypes or assumptions inevitably leads to exclusion because generalizations can’t reflect the diversity of human perspectives. Avoiding assumptions and instead concentrating on inclusion can help you craft experiences that benefit everyone." } ] }, { "heading": "Accessibility", "level": 2, "content": [ { "type": "paragraph", "text": "An inclusive app or game is accessible to everyone. People rely on Apple’s accessibility features — such as VoiceOver, Display Accommodations, closed captioning, Switch Control, and Speak Screen — to customize their devices for their individual needs, so it’s essential to support these features." }, { "type": "paragraph", "text": "It’s also essential to avoid assuming that any disability might prevent someone from wanting to enjoy the experience your software provides. Making an assumption like this can result in designs that limit the potential audience for your app or game. In contrast, when you make each experience accessible, you give everyone the opportunity to benefit from your app or game in ways that work for them." }, { "type": "paragraph", "text": "To help you design an app or game that everyone can enjoy, remember that:" }, { "type": "list", "items": [ "Each disability is a spectrum. For example, visual disabilities range from low vision to complete blindness, and include things like color blindness, blurry vision, light sensitivity, and peripheral vision loss.", "Everyone can experience disabilities. In addition to disabilities that most people experience as they age, there are temporary disabilities — like short-term hearing loss due to an infection — and situational disabilities — like being unable to hear while on a noisy train — that can affect everyone at various times." ] }, { "type": "paragraph", "text": "As you design content that welcomes people of all abilities, consider the following tips." }, { "type": "paragraph", "text": "Avoid images and language that exclude people with disabilities. For example, include people with disabilities when you represent a variety of people, and avoid language that uses a disability to express a negative quality." }, { "type": "paragraph", "text": "Take a people-first approach when writing about people with disabilities. For example, you could describe an individual’s accomplishments and goals before mentioning a disability they may have. If you’re writing about a specific person or community, find out how they self-identify; for more guidance, see Writing about disability." }, { "type": "paragraph", "text": "Prioritize simplicity and perceivability. Prefer familiar, consistent interactions that make tasks simple to perform, and ensure that everyone can perceive your content, whether they use sight, hearing, or touch." }, { "type": "paragraph", "text": "To learn more about making your app or game accessible, see Accessibility." } ] }, { "heading": "Languages", "level": 2, "content": [ { "type": "paragraph", "text": "People expect to customize their device by choosing a language for text and a region for formatting values like date, time, and money. To welcome a global audience, first prepare your software to handle languages and regions other than your own — a process called internationalization — and provide translated text and resources for specific locales. For an overview of internationalization, see Expanding your app to new markets; for developer guidance on localization, see Localization." }, { "type": "paragraph", "text": "Creating an inclusive experience can also help you prepare for localization. For example, using plain language, avoiding unnecessary gender references, representing a variety of people, and avoiding stereotypes and culture-specific content, can put you in a good position to create versions of your software localized into more languages. Using SF Symbols for the glyphs in your app or game can also help streamline localization. In addition to providing many language-specific glyphs, SF Symbols includes glyphs you can use in both left-to-right and right-to-left contexts; for guidance, see Right to left." }, { "type": "paragraph", "text": "As you localize your app or game and related content, also be aware of the ways you use color. Colors often have strong culture-specific meanings, so it’s essential to discover how people respond to specific colors in each locale you support. In some places, for example, white is associated with death or grief, whereas in other places, it’s associated with purity or peace. If you use color as a way to communicate, make sure your color choices communicate the same thing in each version of your software." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Writing inclusively" }, { "type": "paragraph", "text": "Accessibility" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Localization — Xcode" } ] } ], "platforms": [], "related": [ { "title": "Inclusive by design", "url": "/design/human-interface-guidelines/inclusion#Inclusive-by-design" }, { "title": "Welcoming language", "url": "/design/human-interface-guidelines/inclusion#Welcoming-language" }, { "title": "Being approachable", "url": "/design/human-interface-guidelines/inclusion#Being-approachable" }, { "title": "Designing for iOS", "url": "/design/human-interface-guidelines/designing-for-ios" }, { "title": "Designing for iPadOS", "url": "/design/human-interface-guidelines/designing-for-ipados" }, { "title": "Designing for macOS", "url": "/design/human-interface-guidelines/designing-for-macos" }, { "title": "Designing for tvOS", "url": "/design/human-interface-guidelines/designing-for-tvos" }, { "title": "Designing for visionOS", "url": "/design/human-interface-guidelines/designing-for-visionos" }, { "title": "Designing for watchOS", "url": "/design/human-interface-guidelines/designing-for-watchos" }, { "title": "Designing for games", "url": "/design/human-interface-guidelines/designing-for-games" }, { "title": "Onboarding", "url": "/design/human-interface-guidelines/onboarding" }, { "title": "Gender identity", "url": "/design/human-interface-guidelines/inclusion#Gender-identity" }, { "title": "People and settings", "url": "/design/human-interface-guidelines/inclusion#People-and-settings" }, { "title": "Avoiding stereotypes", "url": "/design/human-interface-guidelines/inclusion#Avoiding-stereotypes" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/inclusion#Accessibility" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Languages", "url": "/design/human-interface-guidelines/inclusion#Languages" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Right to left", "url": "/design/human-interface-guidelines/right-to-left" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/inclusion#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/inclusion#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/inclusion#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/inclusion#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/inclusion#Videos" } ], "image_count": 0 }, { "title": "Layout", "url": "https://developer.apple.com/design/human-interface-guidelines/layout", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Your app’s layout helps ground people in your content from the moment they open it. People expect familiar relationships between controls and content to help them use and discover your app’s features, and designing the layout to take advantage of this makes your app feel at home on the platform." }, { "type": "paragraph", "text": "Apple provides templates, guides, and other resources that can help you integrate Apple technologies and design your apps and games to run on all Apple platforms. See Apple Design Resources." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Group related items to help people find the information they want. For example, you might use negative space, background shapes, colors, materials, or separator lines to show when elements are related and to separate information into distinct areas. When you do so, ensure that content and controls remain clearly distinct." }, { "type": "paragraph", "text": "Make essential information easy to find by giving it sufficient space. People want to view the most important information right away, so don’t obscure it by crowding it with nonessential details. You can make secondary information available in other parts of the window, or include it in an additional view." }, { "type": "paragraph", "text": "Extend content to fill the screen or window. Make sure backgrounds and full-screen artwork extend to the edges of the display. Also ensure that scrollable layouts continue all the way to the bottom and the sides of the device screen. Controls and navigation components like sidebars and tab bars appear on top of content rather than on the same plane, so it’s important for your layout to take this into account." }, { "type": "paragraph", "text": "When your content doesn’t span the full window, use a background extension view to provide the appearance of content behind the control layer on either side of the screen, such as beneath the sidebar or inspector. For developer guidance, see backgroundExtensionEffect() and UIBackgroundExtensionView." } ] }, { "heading": "Visual hierarchy", "level": 2, "content": [ { "type": "paragraph", "text": "Differentiate controls from content. Take advantage of the Liquid Glass material to provide a distinct appearance for controls that’s consistent across iOS, iPadOS, and macOS. Instead of a background, use a scroll edge effect to provide a transition between content and the control area. For guidance, see Scroll views." }, { "type": "paragraph", "text": "Place items to convey their relative importance. People often start by viewing items in reading order — that is, from top to bottom and from the leading to trailing side — so it generally works well to place the most important items near the top and leading side of the window, display, or field of view. Be aware that reading order varies by language, and take right to left languages into account as you design." }, { "type": "paragraph", "text": "Align components with one another to make them easier to scan and to communicate organization and hierarchy. Alignment makes an app look neat and organized and can help people track content while scrolling or moving their eyes, making it easier to find information. Along with indentation, alignment can also help people understand an information hierarchy." }, { "type": "paragraph", "text": "Take advantage of progressive disclosure to help people discover content that’s currently hidden. For example, if you can’t display all the items in a large collection at once, you need to indicate that there are additional items that aren’t currently visible. Depending on the platform, you might use a disclosure control, or display parts of items to hint that people can reveal additional content by interacting with the view, such as by scrolling." }, { "type": "paragraph", "text": "Make controls easier to use by providing enough space around them and grouping them in logical sections. If unrelated controls are too close together — or if other content crowds them — they can be difficult for people to tell apart or understand what they do, which can make your app or game hard to use. For guidance, see Toolbars." } ] }, { "heading": "Adaptability", "level": 2, "content": [ { "type": "paragraph", "text": "Every app and game needs to adapt when the device or system context changes. In iOS, iPadOS, tvOS, and visionOS, the system defines a collection of traits that characterize variations in the device environment that can affect the way your app or game looks. Using SwiftUI or Auto Layout can help you ensure that your interface adapts dynamically to these traits and other context changes; if you don’t use these tools, you need to use alternative methods to do the work." }, { "type": "paragraph", "text": "Here are some of the most common device and system variations you need to handle:" }, { "type": "list", "items": [ "Different device screen sizes, resolutions, and color spaces", "Different device orientations (portrait/landscape)", "System features like Dynamic Island and camera controls", "External display support, Display Zoom, and resizable windows on iPad", "Dynamic Type text-size changes", "Locale-based internationalization features like left-to-right/right-to-left layout direction, date/time/number formatting, font variation, and text length" ] }, { "type": "paragraph", "text": "Design a layout that adapts gracefully to context changes while remaining recognizably consistent. People expect your experience to work well and remain familiar when they rotate their device, resize a window, add another display, or switch to a different device. You can help ensure an adaptable interface by respecting system-defined safe areas, margins, and guides (where available) and specifying layout modifiers to fine-tune the placement of views in your interface." }, { "type": "paragraph", "text": "Be prepared for text-size changes. People appreciate apps and games that respond when they choose a different text size. When you support Dynamic Type — a feature that lets people choose the size of visible text in iOS, iPadOS, tvOS, visionOS, and watchOS — your app or game can respond appropriately when people adjust text size. To support Dynamic Type in your Unity-based game, use Apple’s accessibility plug-in (for developer guidance, see Apple – Accessibility). For guidance on displaying text in your app, see Typography." }, { "type": "paragraph", "text": "Preview your app on multiple devices, using different orientations, localizations, and text sizes. You can streamline the testing process by first testing versions of your experience that use the largest and the smallest layouts. Although it’s generally best to preview features like wide-gamut color on actual devices, you can use Xcode Simulator to check for clipping and other layout issues. For example, if your iOS app or game supports landscape mode, you can use Simulator to make sure your layouts look great whether the device rotates left or right." }, { "type": "paragraph", "text": "When necessary, scale artwork in response to display changes. For example, viewing your app or game in a different context — such as on a screen with a different aspect ratio — might make your artwork appear cropped, letterboxed, or pillarboxed. If this happens, don’t change the aspect ratio of the artwork; instead, scale it so that important visual content remains visible. In visionOS, the system automatically scales a window when it moves along the z-axis." } ] }, { "heading": "Guides and safe areas", "level": 2, "content": [ { "type": "paragraph", "text": "A layout guide defines a rectangular region that helps you position, align, and space your content on the screen. The system includes predefined layout guides that make it easy to apply standard margins around content and restrict the width of text for optimal readability. You can also define custom layout guides. For developer guidance, see UILayoutGuide and NSLayoutGuide." }, { "type": "paragraph", "text": "A safe area defines the area within a view that isn’t covered by a toolbar, tab bar, or other views a window might provide. Safe areas are essential for avoiding a device’s interactive and display features, like Dynamic Island on iPhone or the camera housing on some Mac models. For developer guidance, see SafeAreaRegions and Positioning content relative to the safe area." }, { "type": "paragraph", "text": "Respect key display and system features in each platform. When an app or game doesn’t accommodate such features, it doesn’t feel at home in the platform and may be harder for people to use. In addition to helping you avoid display and system features, safe areas can also help you account for interactive components like bars, dynamically repositioning content when sizes change." }, { "type": "paragraph", "text": "For templates that include the guides and safe areas for each platform, see Apple Design Resources." } ] }, { "heading": "iOS", "level": 3, "content": [ { "type": "paragraph", "text": "Aim to support both portrait and landscape orientations. People appreciate apps and games that work well in different device orientations, but sometimes your experience needs to run in only portrait or only landscape. When this is the case, you can rely on people trying both orientations before settling on the one you support — there’s no need to tell people to rotate their device. If your app or game is landscape-only, make sure it runs equally well whether people rotate their device to the left or the right." }, { "type": "paragraph", "text": "Prefer a full-bleed interface for your game. Give players a beautiful interface that fills the screen while accommodating the corner radius, sensor housing, and features like Dynamic Island. If necessary, consider giving players the option to view your game using a letterboxed or pillarboxed appearance." }, { "type": "paragraph", "text": "Avoid full-width buttons. Buttons feel at home in iOS when they respect system-defined margins and are inset from the edges of the screen. If you need to include a full-width button, make sure it harmonizes with the curvature of the hardware and aligns with adjacent safe areas." }, { "type": "paragraph", "text": "Hide the status bar only when it adds value or enhances your experience. The status bar displays information people find useful and it occupies an area of the screen most apps don’t fully use, so it’s generally a good idea to keep it visible. The exception is if you offer an in-depth experience like playing a game or viewing media, where it might make sense to hide the status bar." } ] }, { "heading": "iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "People can freely resize windows down to a minimum width and height, similar to window behavior in macOS. It’s important to account for this resizing behavior and the full range of possible window sizes when designing your layout. For guidance, see Multitasking and Windows." }, { "type": "paragraph", "text": "As someone resizes a window, defer switching to a compact view for as long as possible. Design for a full-screen view first, and only switch to a compact view when a version of the full layout no longer fits. This helps the UI feel more stable and familiar in as many situations as possible. For more complex layouts such as split views, prefer hiding tertiary columns such as inspectors as the view narrows." }, { "type": "paragraph", "text": "Test your layout at common system-provided sizes, and provide smooth transitions. Window controls provide the option to arrange windows to fill halves, thirds, and quadrants of the screen, so it’s important to check your layout at each of these sizes on a variety of devices. Be sure to minimize unexpected UI changes as people adjust down to the minimum and up to the maximum window size." }, { "type": "paragraph", "text": "Consider a convertible tab bar for adaptive navigation. For many apps, you don’t need to choose between a tab bar or sidebar for navigation; instead, you can adopt a style of tab bar that provides both. The app first launches with your choice of a sidebar or a tab bar, and then people can tap to switch between them. As the view resizes, the presentation style changes to fit the width of the view. For guidance, see Tab bars. For developer guidance, see sidebarAdaptable." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "Avoid placing controls or critical information at the bottom of a window. People often move windows so that the bottom edge is below the bottom of the screen." }, { "type": "paragraph", "text": "Avoid displaying content within the camera housing at the top edge of the window. For developer guidance, see NSPrefersDisplaySafeAreaCompatibilityMode." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "Be prepared for a wide range of TV sizes. On Apple TV, layouts don’t automatically adapt to the size of the screen like they do on iPhone or iPad. Instead, apps and games show the same interface on every display. Take extra care in designing your layout so that it looks great in a variety of screen sizes." }, { "type": "paragraph", "text": "Adhere to the screen’s safe area. Inset primary content 60 points from the top and bottom of the screen, and 80 points from the sides. It can be difficult for people to see content that close to the edges, and unintended cropping can occur due to overscanning on older TVs. Allow only partially displayed offscreen content and elements that deliberately flow offscreen to appear outside this zone." }, { "type": "paragraph", "text": "Include appropriate padding between focusable elements. When you use UIKit and the focus APIs, an element gets bigger when it comes into focus. Consider how elements look when they’re focused, and make sure you don’t let them overlap important information. For developer guidance, see About focus interactions for Apple TV." } ] }, { "heading": "Grids", "level": 4, "content": [ { "type": "paragraph", "text": "The following grid layouts provide an optimal viewing experience. Be sure to use appropriate spacing between unfocused rows and columns to prevent overlap when an item comes into focus." }, { "type": "paragraph", "text": "If you use the UIKit collection view flow element, the number of columns in a grid is automatically determined based on the width and spacing of your content. For developer guidance, see UICollectionViewFlowLayout." } ] }, { "heading": "Two-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "860 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Three-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "560 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Four-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "410 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Five-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "320 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Six-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "260 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Seven-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "217 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Eight-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "184 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] } ] }, { "heading": "Nine-column grid", "level": 4, "content": [ { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Unfocused content width", "160 pt" ], [ "Horizontal spacing", "40 pt" ], [ "Minimum vertical spacing", "100 pt" ] ] }, { "type": "paragraph", "text": "Include additional vertical spacing for titled rows. If a row has a title, provide enough spacing between the bottom of the previous unfocused row and the center of the title to avoid crowding. Also provide spacing between the bottom of the title and the top of the unfocused items in the row." }, { "type": "paragraph", "text": "Use consistent spacing. When content isn’t consistently spaced, it no longer looks like a grid and it’s harder for people to scan." }, { "type": "paragraph", "text": "Make partially hidden content look symmetrical. To help direct attention to the fully visible content, keep partially hidden offscreen content the same width on each side of the screen." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "The guidance below can help you lay out content within the windows of your visionOS app or game, making it feel familiar and easy to use. For guidance on displaying windows in space and best practices for using depth, scale, and field of view in your visionOS app, see Spatial layout. To learn more about visionOS window components, see Windows > visionOS." }, { "type": "note", "text": "NoteWhen you add depth to content in a standard window, the content extends beyond the window’s bounds along the z-axis. If content extends too far along the z-axis, the system clips it." }, { "type": "paragraph", "text": "Consider centering the most important content and controls in your app or game. Often, people can more easily discover and interact with content when it’s near the middle of a window, especially when the window is large." }, { "type": "paragraph", "text": "Keep a window’s content within its bounds. In visionOS, the system displays window controls just outside a window’s bounds in the XY plane. For example, the Share menu appears above the window and the controls for resizing, moving, and closing the window appear below it. Letting 2D or 3D content encroach on these areas can make the system-provided controls, especially those below the window, difficult for people to use." }, { "type": "paragraph", "text": "If you need to display additional controls that don’t belong within a window, use an ornament. An ornament lets you offer app controls that remain visually associated with a window without interfering with the system-provided controls. For example, a window’s toolbar and tab bar appear as ornaments. For guidance, see Ornaments." }, { "type": "paragraph", "text": "Make a window’s interactive components easy for people to look at. You need to include enough space around an interactive component so that visually identifying it is easy and comfortable, and to prevent the system-provided hover effect from obscuring other content. For example, place buttons so their centers are at least 60 points apart. For guidance, see Eyes, Spatial layout, and Buttons > visionOS." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Design your content to extend from one edge of the screen to the other. The Apple Watch bezel provides a natural visual padding around your content. To avoid wasting valuable space, consider minimizing the padding between elements." }, { "type": "paragraph", "text": "Avoid placing more than two or three controls side by side in your interface. As a general rule, display no more than three buttons that contain glyphs — or two buttons that contain text — in a row. Although it’s usually better to let text buttons span the full width of the screen, two side-by-side buttons with short text labels can also work well, as long as the screen doesn’t scroll." }, { "type": "paragraph", "text": "Support autorotation in views people might want to show others. When people flip their wrist away, apps typically respond to the motion by sleeping the display, but in some cases it makes sense to autorotate the content. For example, a wearer might want to show an image to a friend or display a QR code to a reader. For developer guidance, see isAutorotating." } ] }, { "heading": "iOS, iPadOS device screen dimensions", "level": 3, "content": [ { "type": "table", "rows": [ [ "Model", "Dimensions (portrait)" ], [ "iPad Pro 12.9-inch", "1024x1366 pt (2048x2732 px @2x)" ], [ "iPad Pro 11-inch", "834x1194 pt (1668x2388 px @2x)" ], [ "iPad Pro 10.5-inch", "834x1194 pt (1668x2388 px @2x)" ], [ "iPad Pro 9.7-inch", "768x1024 pt (1536x2048 px @2x)" ], [ "iPad Air 13-inch", "1024x1366 pt (2048x2732 px @2x)" ], [ "iPad Air 11-inch", "820x1180 pt (1640x2360 px @2x)" ], [ "iPad Air 10.9-inch", "820x1180 pt (1640x2360 px @2x)" ], [ "iPad Air 10.5-inch", "834x1112 pt (1668x2224 px @2x)" ], [ "iPad Air 9.7-inch", "768x1024 pt (1536x2048 px @2x)" ], [ "iPad 11-inch", "820x1180 pt (1640x2360 px @2x)" ], [ "iPad 10.2-inch", "810x1080 pt (1620x2160 px @2x)" ], [ "iPad 9.7-inch", "768x1024 pt (1536x2048 px @2x)" ], [ "iPad mini 8.3-inch", "744x1133 pt (1488x2266 px @2x)" ], [ "iPad mini 7.9-inch", "768x1024 pt (1536x2048 px @2x)" ], [ "iPhone 17 Pro Max", "440x956 pt (1320x2868 px @3x)" ], [ "iPhone 17 Pro", "402x874 pt (1206x2622 px @3x)" ], [ "iPhone Air", "420x912 pt (1260x2736 px @3x)" ], [ "iPhone 17", "402x874 pt (1206x2622 px @3x)" ], [ "iPhone 16 Pro Max", "440x956 pt (1320x2868 px @3x)" ], [ "iPhone 16 Pro", "402x874 pt (1206x2622 px @3x)" ], [ "iPhone 16 Plus", "430x932 pt (1290x2796 px @3x)" ], [ "iPhone 16", "393x852 pt (1179x2556 px @3x)" ], [ "iPhone 16e", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 15 Pro Max", "430x932 pt (1290x2796 px @3x)" ], [ "iPhone 15 Pro", "393x852 pt (1179x2556 px @3x)" ], [ "iPhone 15 Plus", "430x932 pt (1290x2796 px @3x)" ], [ "iPhone 15", "393x852 pt (1179x2556 px @3x)" ], [ "iPhone 14 Pro Max", "430x932 pt (1290x2796 px @3x)" ], [ "iPhone 14 Pro", "393x852 pt (1179x2556 px @3x)" ], [ "iPhone 14 Plus", "428x926 pt (1284x2778 px @3x)" ], [ "iPhone 14", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 13 Pro Max", "428x926 pt (1284x2778 px @3x)" ], [ "iPhone 13 Pro", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 13", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 13 mini", "375x812 pt (1125x2436 px @3x)" ], [ "iPhone 12 Pro Max", "428x926 pt (1284x2778 px @3x)" ], [ "iPhone 12 Pro", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 12", "390x844 pt (1170x2532 px @3x)" ], [ "iPhone 12 mini", "375x812 pt (1125x2436 px @3x)" ], [ "iPhone 11 Pro Max", "414x896 pt (1242x2688 px @3x)" ], [ "iPhone 11 Pro", "375x812 pt (1125x2436 px @3x)" ], [ "iPhone 11", "414x896 pt (828x1792 px @2x)" ], [ "iPhone XS Max", "414x896 pt (1242x2688 px @3x)" ], [ "iPhone XS", "375x812 pt (1125x2436 px @3x)" ], [ "iPhone XR", "414x896 pt (828x1792 px @2x)" ], [ "iPhone X", "375x812 pt (1125x2436 px @3x)" ], [ "iPhone 8 Plus", "414x736 pt (1080x1920 px @3x)" ], [ "iPhone 8", "375x667 pt (750x1334 px @2x)" ], [ "iPhone 7 Plus", "414x736 pt (1080x1920 px @3x)" ], [ "iPhone 7", "375x667 pt (750x1334 px @2x)" ], [ "iPhone 6s Plus", "414x736 pt (1080x1920 px @3x)" ], [ "iPhone 6s", "375x667 pt (750x1334 px @2x)" ], [ "iPhone 6 Plus", "414x736 pt (1080x1920 px @3x)" ], [ "iPhone 6", "375x667 pt (750x1334 px @2x)" ], [ "iPhone SE 4.7-inch", "375x667 pt (750x1334 px @2x)" ], [ "iPhone SE 4-inch", "320x568 pt (640x1136 px @2x)" ], [ "iPod touch 5th generation and later", "320x568 pt (640x1136 px @2x)" ] ] }, { "type": "note", "text": "NoteAll scale factors in the table above are UIKit scale factors, which may differ from native scale factors. For developer guidance, see scale and nativeScale." } ] }, { "heading": "iOS, iPadOS device size classes", "level": 3, "content": [ { "type": "paragraph", "text": "A size class is a value that’s either regular or compact, where regular refers to a larger screen or a screen in landscape orientation and compact refers to a smaller screen or a screen in portrait orientation. For developer guidance, see UserInterfaceSizeClass." }, { "type": "paragraph", "text": "Different size class combinations apply to the full-screen experience on different devices, based on screen size." }, { "type": "table", "rows": [ [ "Model", "Portrait orientation", "Landscape orientation" ], [ "iPad Pro 12.9-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad Pro 11-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad Pro 10.5-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad Air 13-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad Air 11-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad 11-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad 9.7-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPad mini 7.9-inch", "Regular width, regular height", "Regular width, regular height" ], [ "iPhone 17 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 17 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone Air", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 17", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 16 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 16 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 16 Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 16", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 16e", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 15 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 15 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 15 Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 15", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 14 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 14 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 14 Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 14", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 13 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 13 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 13", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 13 mini", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 12 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 12 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 12", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 12 mini", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 11 Pro Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 11 Pro", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 11", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone XS Max", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone XS", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone XR", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone X", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 8 Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 8", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 7 Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 7", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone 6s Plus", "Compact width, regular height", "Regular width, compact height" ], [ "iPhone 6s", "Compact width, regular height", "Compact width, compact height" ], [ "iPhone SE", "Compact width, regular height", "Compact width, compact height" ], [ "iPod touch 5th generation and later", "Compact width, regular height", "Compact width, compact height" ] ] } ] }, { "heading": "watchOS device screen dimensions", "level": 3, "content": [ { "type": "table", "rows": [ [ "Series", "Size", "Width (pixels)", "Height (pixels)" ], [ "Apple Watch Ultra (3rd generation)", "49mm", "422", "514" ], [ "10, 11", "42mm", "374", "446" ], [ "10, 11", "46mm", "416", "496" ], [ "Apple Watch Ultra (1st and 2nd generations)", "49mm", "410", "502" ], [ "7, 8, and 9", "41mm", "352", "430" ], [ "7, 8, and 9", "45mm", "396", "484" ], [ "4, 5, 6, and SE (all generations)", "40mm", "324", "394" ], [ "4, 5, 6, and SE (all generations)", "44mm", "368", "448" ], [ "1, 2, and 3", "38mm", "272", "340" ], [ "1, 2, and 3", "42mm", "312", "390" ] ] } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Right to left" }, { "type": "paragraph", "text": "Spatial layout" }, { "type": "paragraph", "text": "Layout and organization" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Composing custom layouts with SwiftUI — SwiftUI" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 9, 2025", "Added specifications for iPhone 17, iPhone Air, iPhone 17 Pro, iPhone 17 Pro Max, Apple Watch SE 3, Apple Watch Series 11, and Apple Watch Ultra 3." ], [ "June 9, 2025", "Added guidance for Liquid Glass." ], [ "March 7, 2025", "Added specifications for iPhone 16e, iPad 11-inch, iPad Air 11-inch, and iPad Air 13-inch." ], [ "September 9, 2024", "Added specifications for iPhone 16, iPhone 16 Plus, iPhone 16 Pro, iPhone 16 Pro Max, and Apple Watch Series 10." ], [ "June 10, 2024", "Made minor corrections and organizational updates." ], [ "February 2, 2024", "Enhanced guidance for avoiding system controls in iPadOS app layouts, and added specifications for 10.9-inch iPad Air and 8.3-inch iPad mini." ], [ "December 5, 2023", "Clarified guidance on centering content in a visionOS window." ], [ "September 15, 2023", "Added specifications for iPhone 15 Pro Max, iPhone 15 Pro, iPhone 15 Plus, iPhone 15, Apple Watch Ultra 2, and Apple Watch SE." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "September 14, 2022", "Added specifications for iPhone 14 Pro Max, iPhone 14 Pro, iPhone 14 Plus, iPhone 14, and Apple Watch Ultra." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/layout#Best-practices" }, { "title": "Visual hierarchy", "url": "/design/human-interface-guidelines/layout#Visual-hierarchy" }, { "title": "Scroll views", "url": "/design/human-interface-guidelines/scroll-views" }, { "title": "field of view", "url": "/design/human-interface-guidelines/spatial-layout#Field-of-view" }, { "title": "right to left", "url": "/design/human-interface-guidelines/right-to-left" }, { "title": "disclosure control", "url": "/design/human-interface-guidelines/disclosure-controls" }, { "title": "Toolbars", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "Adaptability", "url": "/design/human-interface-guidelines/layout#Adaptability" }, { "title": "Dynamic Type", "url": "/design/human-interface-guidelines/typography#Supporting-Dynamic-Type" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "scales", "url": "/design/human-interface-guidelines/spatial-layout#Scale" }, { "title": "Guides and safe areas", "url": "/design/human-interface-guidelines/layout#Guides-and-safe-areas" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/layout#Platform-considerations" }, { "title": "iOS", "url": "/design/human-interface-guidelines/layout#iOS" }, { "title": "iPadOS", "url": "/design/human-interface-guidelines/layout#iPadOS" }, { "title": "Multitasking", "url": "/design/human-interface-guidelines/multitasking#iPadOS" }, { "title": "Windows", "url": "/design/human-interface-guidelines/windows#iPadOS" }, { "title": "split views", "url": "/design/human-interface-guidelines/split-views" }, { "title": "Tab bars", "url": "/design/human-interface-guidelines/tab-bars" }, { "title": "macOS", "url": "/design/human-interface-guidelines/layout#macOS" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/layout#tvOS" }, { "title": "Grids", "url": "/design/human-interface-guidelines/layout#Grids" }, { "title": "Two-column grid", "url": "/design/human-interface-guidelines/layout#Two-column-grid" }, { "title": "Three-column grid", "url": "/design/human-interface-guidelines/layout#Three-column-grid" }, { "title": "Four-column grid", "url": "/design/human-interface-guidelines/layout#Four-column-grid" }, { "title": "Five-column grid", "url": "/design/human-interface-guidelines/layout#Five-column-grid" }, { "title": "Six-column grid", "url": "/design/human-interface-guidelines/layout#Six-column-grid" }, { "title": "Seven-column grid", "url": "/design/human-interface-guidelines/layout#Seven-column-grid" }, { "title": "Eight-column grid", "url": "/design/human-interface-guidelines/layout#Eight-column-grid" }, { "title": "Nine-column grid", "url": "/design/human-interface-guidelines/layout#Nine-column-grid" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/layout#visionOS" }, { "title": "Spatial layout", "url": "/design/human-interface-guidelines/spatial-layout" }, { "title": "Windows > visionOS", "url": "/design/human-interface-guidelines/windows#visionOS" }, { "title": "Ornaments", "url": "/design/human-interface-guidelines/ornaments" }, { "title": "Eyes", "url": "/design/human-interface-guidelines/eyes" }, { "title": "Buttons > visionOS", "url": "/design/human-interface-guidelines/buttons#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/layout#watchOS" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/layout#Specifications" }, { "title": "iOS, iPadOS device screen dimensions", "url": "/design/human-interface-guidelines/layout#iOS-iPadOS-device-screen-dimensions" }, { "title": "iOS, iPadOS device size classes", "url": "/design/human-interface-guidelines/layout#iOS-iPadOS-device-size-classes" }, { "title": "watchOS device screen dimensions", "url": "/design/human-interface-guidelines/layout#watchOS-device-screen-dimensions" }, { "title": "Resources", "url": "/design/human-interface-guidelines/layout#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/layout#Related" }, { "title": "Layout and organization", "url": "/design/human-interface-guidelines/layout-and-organization" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/layout#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/layout#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/layout#Change-log" } ], "image_count": 0 }, { "title": "Materials", "url": "https://developer.apple.com/design/human-interface-guidelines/materials", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Materials help visually separate foreground elements, such as text and controls, from background elements, such as content and solid colors. By allowing color to pass through from background to foreground, a material establishes visual hierarchy to help people more easily retain a sense of place." }, { "type": "paragraph", "text": "Apple platforms feature two types of materials: Liquid Glass, and standard materials. Liquid Glass is a dynamic material that unifies the design language across Apple platforms, allowing you to present controls and navigation without obscuring underlying content. In contrast to Liquid Glass, the standard materials help with visual differentiation within the content layer." } ] }, { "heading": "Liquid Glass", "level": 2, "content": [ { "type": "paragraph", "text": "Liquid Glass forms a distinct functional layer for controls and navigation elements — like tab bars and sidebars — that floats above the content layer, establishing a clear visual hierarchy between functional elements and content. Liquid Glass allows content to scroll and peek through from beneath these elements to give the interface a sense of dynamism and depth, all while maintaining legibility for controls and navigation." }, { "type": "paragraph", "text": "Don’t use Liquid Glass in the content layer. Liquid Glass works best when it provides a clear distinction between interactive elements and content, and including it in the content layer can result in unnecessary complexity and a confusing visual hierarchy. Instead, use standard materials for elements in the content layer, such as app backgrounds. An exception to this is for controls in the content layer with a transient interactive element like sliders and toggles; in these cases, the element takes on a Liquid Glass appearance to emphasize its interactivity when a person activates it." }, { "type": "paragraph", "text": "Use Liquid Glass effects sparingly. Standard components from system frameworks pick up the appearance and behavior of this material automatically. If you apply Liquid Glass effects to a custom control, do so sparingly. Liquid Glass seeks to bring attention to the underlying content, and overusing this material in multiple custom controls can provide a subpar user experience by distracting from that content. Limit these effects to the most important functional elements in your app. For developer guidance, see Applying Liquid Glass to custom views." }, { "type": "paragraph", "text": "Only use clear Liquid Glass for components that appear over visually rich backgrounds. Liquid Glass provides two variants — regular and clear — that you can choose when building custom components or styling some system components. The appearance of these variants can differ in response to certain system settings, like if people choose a preferred look for Liquid Glass in their device’s display settings, or turn on accessibility settings that reduce transparency or increase contrast in the interface." }, { "type": "paragraph", "text": "The regular variant blurs and adjusts the luminosity of background content to maintain legibility of text and other foreground elements. Scroll edge effects further enhance legibility by blurring and reducing the opacity of background content. Most system components use this variant. Use the regular variant when background content might create legibility issues, or when components have a significant amount of text, such as alerts, sidebars, or popovers." }, { "type": "paragraph", "text": "On dark background" }, { "type": "paragraph", "text": "On light background" }, { "type": "paragraph", "text": "The clear variant is highly translucent, which is ideal for prioritizing the visibility of the underlying content and ensuring visually rich background elements remain prominent. Use this variant for components that float above media backgrounds — such as photos and videos — to create a more immersive content experience." }, { "type": "paragraph", "text": "For optimal contrast and legibility, determine whether to add a dimming layer behind components with clear Liquid Glass:" }, { "type": "list", "items": [ "If the underlying content is bright, consider adding a dark dimming layer of 35% opacity. For developer guidance, see clear.", "If the underlying content is sufficiently dark, or if you use standard media playback controls from AVKit that provide their own dimming layer, you don’t need to apply a dimming layer." ] }, { "type": "paragraph", "text": "For guidance about the use of color, see Liquid Glass color." } ] }, { "heading": "Standard materials", "level": 2, "content": [ { "type": "paragraph", "text": "Use standard materials and effects — such as blur, vibrancy, and blending modes — to convey a sense of structure in the content beneath Liquid Glass." }, { "type": "paragraph", "text": "Choose materials and effects based on semantic meaning and recommended usage. Avoid selecting a material or effect based on the apparent color it imparts to your interface, because system settings can change its appearance and behavior. Instead, match the material or vibrancy style to your specific use case." }, { "type": "paragraph", "text": "Help ensure legibility by using vibrant colors on top of materials. When you use system-defined vibrant colors, you don’t need to worry about colors seeming too dark, bright, saturated, or low contrast in different contexts. Regardless of the material you choose, use vibrant colors on top of it. For guidance, see System colors." }, { "type": "paragraph", "text": "Poor contrast between the material and systemGray3 label" }, { "type": "paragraph", "text": "Good contrast between the material and vibrant color label" }, { "type": "paragraph", "text": "Consider contrast and visual separation when choosing a material to combine with blur and vibrancy effects. For example, consider that:" }, { "type": "list", "items": [ "Thicker materials, which are more opaque, can provide better contrast for text and other elements with fine features.", "Thinner materials, which are more translucent, can help people retain their context by providing a visible reminder of the content that’s in the background." ] }, { "type": "paragraph", "text": "For developer guidance, see Material." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "In addition to Liquid Glass, iOS and iPadOS continue to provide four standard materials — ultra-thin, thin, regular (default), and thick — which you can use in the content layer to help create visual distinction." }, { "type": "paragraph", "text": "ultraThin" }, { "type": "paragraph", "text": "thin" }, { "type": "paragraph", "text": "regular" }, { "type": "paragraph", "text": "thick" }, { "type": "paragraph", "text": "iOS and iPadOS also define vibrant colors for labels, fills, and separators that are specifically designed to work with each material. Labels and fills both have several levels of vibrancy; separators have one level. The name of a level indicates the relative amount of contrast between an element and the background: The default level has the highest contrast, whereas quaternary (when it exists) has the lowest contrast." }, { "type": "paragraph", "text": "Except for quaternary, you can use the following vibrancy values for labels on any material. In general, avoid using quaternary on top of the thin and ultraThin materials, because the contrast is too low." }, { "type": "list", "items": [ "UIVibrancyEffectStyle.label (default)", "UIVibrancyEffectStyle.secondaryLabel", "UIVibrancyEffectStyle.tertiaryLabel", "UIVibrancyEffectStyle.quaternaryLabel" ] }, { "type": "paragraph", "text": "You can use the following vibrancy values for fills on all materials." }, { "type": "list", "items": [ "UIVibrancyEffectStyle.fill (default)", "UIVibrancyEffectStyle.secondaryFill", "UIVibrancyEffectStyle.tertiaryFill" ] }, { "type": "paragraph", "text": "The system provides a single, default vibrancy value for a separator, which works well on all materials." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "macOS provides several standard materials with designated purposes, and vibrant versions of all system colors. For developer guidance, see NSVisualEffectView.Material." }, { "type": "paragraph", "text": "Choose when to allow vibrancy in custom views and controls. Depending on configuration and system settings, system views and controls use vibrancy to make foreground content stand out against any background. Test your interface in a variety of contexts to discover when vibrancy enhances the appearance and improves communication." }, { "type": "paragraph", "text": "Choose a background blending mode that complements your interface design. macOS defines two modes that blend background content: behind window and within window. For developer guidance, see NSVisualEffectView.BlendingMode." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "In tvOS, Liquid Glass appears throughout navigation elements and system experiences such as Top Shelf and Control Center. Certain interface elements, like image views and buttons, adopt Liquid Glass when they gain focus." }, { "type": "paragraph", "text": "In addition to Liquid Glass, tvOS continues to provide standard materials, which you can use to help define structure in the content layer. The thickness of a standard material affects how prominently the underlying content shows through. For example, consider using standard materials in the following ways:" }, { "type": "table", "rows": [ [ "Material", "Recommended for" ], [ "ultraThin", "Full-screen views that require a light color scheme" ], [ "thin", "Overlay views that partially obscure onscreen content and require a light color scheme" ], [ "regular", "Overlay views that partially obscure onscreen content" ], [ "thick", "Overlay views that partially obscure onscreen content and require a dark color scheme" ] ] } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In visionOS, windows generally use an unmodifiable system-defined material called glass that helps people stay grounded by letting light, the current Environment, virtual content, and objects in people’s surroundings show through. Glass is an adaptive material that limits the range of background color information so a window can continue to provide contrast for app content while becoming brighter or darker depending on people’s physical surroundings and other virtual content." }, { "type": "note", "text": "NotevisionOS doesn’t have a distinct Dark Mode setting. Instead, glass automatically adapts to the luminance of the objects and colors behind it." }, { "type": "paragraph", "text": "Prefer translucency to opaque colors in windows. Areas of opacity can block people’s view, making them feel constricted and reducing their awareness of the virtual and physical objects around them." }, { "type": "paragraph", "text": "If necessary, choose materials that help you create visual separations or indicate interactivity in your app. If you need to create a custom component, you may need to specify a system material for it. Use the following examples for guidance." }, { "type": "list", "items": [ "The thin material brings attention to interactive elements like buttons and selected items.", "The regular material can help you visually separate sections of your app, like a sidebar or a grouped table view.", "The thick material lets you create a dark element that remains visually distinct when it’s on top of an area that uses a regular background." ] }, { "type": "paragraph", "text": "To ensure foreground content remains legible when it displays on top of a material, visionOS applies vibrancy to text, symbols, and fills. Vibrancy enhances the sense of depth by pulling light and color forward from both virtual and physical surroundings." }, { "type": "paragraph", "text": "visionOS defines three vibrancy values that help you communicate a hierarchy of text, symbols, and fills." }, { "type": "list", "items": [ "Use UIVibrancyEffectStyle.label for standard text.", "Use UIVibrancyEffectStyle.secondaryLabel for descriptive text like footnotes and subtitles.", "Use UIVibrancyEffectStyle.tertiaryLabel for inactive elements, and only when text doesn’t need high legibility." ] }, { "type": "paragraph", "text": "label" }, { "type": "paragraph", "text": "secondaryLabel" }, { "type": "paragraph", "text": "tertiaryLabel" } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Use materials to provide context in a full-screen modal view. Because full-screen modal views are common in watchOS, the contrast provided by material layers can help orient people in your app and distinguish controls and system elements from other content. Avoid removing or replacing material backgrounds for modal sheets when they’re provided by default." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Color" }, { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Dark Mode" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Adopting Liquid Glass" }, { "type": "paragraph", "text": "glassEffect(_:in:) — SwiftUI" }, { "type": "paragraph", "text": "Material — SwiftUI" }, { "type": "paragraph", "text": "UIVisualEffectView — UIKit" }, { "type": "paragraph", "text": "NSVisualEffectView — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 9, 2025", "Updated guidance for Liquid Glass." ], [ "June 9, 2025", "Added guidance for Liquid Glass." ], [ "August 6, 2024", "Added platform-specific art." ], [ "December 5, 2023", "Updated descriptions of the various material types, and clarified terms related to vibrancy and material thickness." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "June 5, 2023", "Added guidance on using materials to provide context and orientation in watchOS apps." ] ] } ] } ], "platforms": [], "related": [ { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "standard materials", "url": "/design/human-interface-guidelines/materials#Standard-materials" }, { "title": "sliders", "url": "/design/human-interface-guidelines/sliders" }, { "title": "toggles", "url": "/design/human-interface-guidelines/toggles" }, { "title": "Liquid Glass color", "url": "/design/human-interface-guidelines/color#Liquid-Glass-color" }, { "title": "System colors", "url": "/design/human-interface-guidelines/color#System-colors" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/materials#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/materials#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/materials#macOS" }, { "title": "system colors", "url": "/design/human-interface-guidelines/color#Specifications" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/materials#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/materials#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/materials#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/materials#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/materials#Related" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Dark Mode", "url": "/design/human-interface-guidelines/dark-mode" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/materials#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/materials#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/materials#Change-log" } ], "image_count": 0 }, { "title": "Menus", "url": "https://developer.apple.com/design/human-interface-guidelines/menus", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Menus are ubiquitous in apps and games, so most people already know how to use them. Whether you use system-provided components or custom ones, people expect menus to behave in familiar ways. For example, people understand that opening a menu reveals one or more menu items, each of which represents a command, option, or state that affects the current selection or context. The guidance for labeling and organizing menu items applies to all types of menus in all experiences." }, { "type": "note", "text": "NoteSeveral system-provided components also include menus that support specific use cases. For example, a pop-up button or pull-down button can reveal a menu of options directly related to its action; a context menu lets people access a small number of frequently used actions relevant to their current view or task; and in macOS and iPadOS, menu bar menus contain all the commands people can perform in the app or game." } ] }, { "heading": "Labels", "level": 2, "content": [ { "type": "paragraph", "text": "A menu item’s label describes what it does and may include a symbol if it helps to clarify meaning. In an app, a menu item can also display the associated keyboard command, if there is one; in a game, a menu item rarely displays a keyboard command because a game typically needs to handle input from a wider range of devices and may offer game-specific mappings for various keys." }, { "type": "note", "text": "NoteDepending on menu layout, an iOS, iPadOS, or visionOS app can display a few unlabeled menu items that use only symbols or icons to identify them. For guidance, see visionOS and iOS, iPadOS." }, { "type": "paragraph", "text": "For each menu item, write a label that clearly and succinctly describes it. In general, label a menu item that initiates an action using a verb or verb phrase that describes the action, such as View, Close, or Select. For guidance labeling menu items that show and hide something in the interface or show the currently selected state of something, see Toggled items. As with all the copy you write, let your app’s or game’s communication style guide the tone of the menu-item labels you create." }, { "type": "paragraph", "text": "To be consistent with platform experiences, use title-style capitalization. Although a game might have a different writing style, generally prefer using title-style capitalization, which capitalizes every word except articles, coordinating conjunctions, and short prepositions, and capitalizes the last word in the label, regardless of the part of speech. For complete guidance on this style of capitalization in English, see title-style capitalization." }, { "type": "paragraph", "text": "Remove articles like a, an, and the from menu-item labels to save space. In English, articles always lengthen labels, but rarely enhance understanding. For example, changing a menu-item label from View Settings to View the Settings doesn’t provide additional clarification." }, { "type": "paragraph", "text": "Show people when a menu item is unavailable. An unavailable menu item often appears dimmed and doesn’t respond to interactions. If all of a menu’s items are unavailable, the menu itself needs to remain available so people can open it and learn about the commands it contains." }, { "type": "paragraph", "text": "Append an ellipsis to a menu item’s label when the action requires more information before it can complete. The ellipsis character (…) signals that people need to input information or make additional choices, typically within another view." } ] }, { "heading": "Icons", "level": 2, "content": [ { "type": "paragraph", "text": "Represent menu item actions with familiar icons. Icons help people recognize common actions throughout your app. Use the same icons as the system to represent actions such as Copy, Share, and Delete, wherever they appear. For a list of icons that represent common actions, see Standard icons." }, { "type": "paragraph", "text": "Don’t display an icon if you can’t find one that clearly represents the menu item. Not all menu items need an icon. Be careful when adding icons for custom menu items to avoid confusion with other existing actions, and don’t add icons just for the sake of ornamentation." }, { "type": "paragraph", "text": "Use a single icon to introduce a group of similar items. Instead of adding individual icons for each action, or reusing the same icon for all of them, establish a common theme with the symbol for the first item and rely on the menu item text to keep the remaining items distinct." } ] }, { "heading": "Organization", "level": 2, "content": [ { "type": "paragraph", "text": "Organizing menu items in ways that reflect how people use your app or game can make your experience feel straightforward and easy to use." }, { "type": "paragraph", "text": "Prefer listing important or frequently used menu items first. People tend to start scanning a menu from the top, so listing high-priority items first often means that people can find what they want without reading the entire menu." }, { "type": "paragraph", "text": "Consider grouping logically related items. For example, grouping editing commands like Copy, Cut, and Paste or camera commands like Look Up, Look Down, and Look Left can help people remember where to find them. To help people visually distinguish such groups, use a separator. Depending on the platform and type of menu, a separator appears between groups of items as a horizontal line or a short gap in the menu’s background appearance." }, { "type": "paragraph", "text": "Prefer keeping all logically related commands in the same group, even if the commands don’t all have the same importance. For example, people generally use Paste and Match Style much less often than they use Paste, but they expect to find both commands in the same group that contains more frequently used editing commands like Copy and Cut." }, { "type": "paragraph", "text": "Be mindful of menu length. People need more time and attention to read a long menu, which means they may miss the command they want. If a menu is too long, consider dividing it into separate menus. Alternatively, you might be able to use a submenu to shorten the list, such as listing difficulty levels in a submenu of a New Game menu item. The exception is when a menu contains user-defined or dynamically generated content, like the History and Bookmarks menus in Safari. People expect such a menu to accommodate all the items they add to it, so a long menu is fine, and scrolling is acceptable." } ] }, { "heading": "Submenus", "level": 2, "content": [ { "type": "paragraph", "text": "Sometimes, a menu item can reveal a set of closely related items in a subordinate list called a submenu. A menu item indicates the presence of a submenu by displaying a symbol — like a chevron — after its label. Submenus are functionally identical to menus, aside from their hierarchical positioning." }, { "type": "paragraph", "text": "Use submenus sparingly. Each submenu adds complexity to the interface and hides the items it contains. You might consider creating a submenu when a term appears in more than two menu items in the same group. For example, instead of offering separate menu items for Sort by Date, Sort by Score, and Sort by Time, a game could present a menu item that uses a submenu to list the sorting options Date, Score, and Time. It generally works well to use the repeated term — in this case, Sort by — in the menu item’s label to help people predict the contents of the submenu." }, { "type": "paragraph", "text": "Limit the depth and length of submenus. It can be difficult for people to reveal multiple levels of hierarchical submenus, so it’s generally best to restrict them to a single level. Also, if a submenu contains more than about five items, consider creating a new menu." }, { "type": "paragraph", "text": "Make sure a submenu remains available even when its nested menu items are unavailable. A submenu item — like all menu items — needs to let people open it and learn about the commands it contains." }, { "type": "paragraph", "text": "Prefer using a submenu to indenting menu items. Using indentation is inconsistent with the system and doesn’t clearly express the relationships between the menu items." } ] }, { "heading": "Toggled items", "level": 2, "content": [ { "type": "paragraph", "text": "Menu items often represent attributes or objects that people can turn on or off. If you want to avoid listing a separate menu item for each state, it can be efficient to create a single, toggled menu item that communicates the current state and lets people change it." }, { "type": "paragraph", "text": "Consider using a changeable label that describes an item’s current state. For example, instead of listing two menu items like Show Map and Hide Map, you could include one menu item whose label changes from Show Map to Hide Map, depending on whether the map is visible." }, { "type": "paragraph", "text": "Include a verb if a changeable label isn’t clear enough. For example, people might not know whether the changeable labels HDR On and HDR Off describe actions or states. If you needed to clarify that these items represent actions, you could add verbs to the labels, like Turn HDR On and Turn HDR Off." }, { "type": "paragraph", "text": "If necessary, display both menu items instead of one toggled item. Sometimes, it helps people to view both actions or states at the same time. For example, a game could list both Take Account Online and Take Account Offline items, so when someone’s account is online, only the Take Account Offline menu item appears available." }, { "type": "paragraph", "text": "Consider using a checkmark to show that an attribute is currently in effect. It’s easy for people to scan for checkmarks in a list of attributes to find the ones that are selected. For example, in the standard Format > Font menu, checkmarks can make it easy for people notice the styles that apply to selected text." }, { "type": "paragraph", "text": "Consider offering a menu item that makes it easy to remove multiple toggled attributes. For example, if you let people apply several styles to selected text, it can work well to provide a menu item — such as Plain — that removes all applied formatting attributes at one time." } ] }, { "heading": "In-game menus", "level": 2, "content": [ { "type": "paragraph", "text": "In-game menus give players ways to control gameplay as well as determine settings for the game as a whole." }, { "type": "paragraph", "text": "Let players navigate in-game menus using the platform’s default interaction method. People expect to use the same interactions to navigate your menus as they use for navigating other menus on the device. For example, players expect to navigate your game menus using touch in iOS and iPadOS, and direct and indirect gestures in visionOS." }, { "type": "paragraph", "text": "Make sure your menus remain easy to open and read on all platforms you support. Each platform defines specific sizes that work best for fonts and interaction targets. Sometimes, scaling your game content to display on a different screen — especially a mobile device screen — can make in-game menus too small for people to read or interact with. If this happens, modify the size of the tap targets and consider alternative ways to communicate the menu’s content. For guidance, see Typography and Touch controls." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for macOS, tvOS, or watchOS." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "In iOS and iPadOS, a menu can display items in one of the following three layouts." }, { "type": "list", "items": [ "Small. A row of four items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon, but no label.", "Medium. A row of three items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon above a short label.", "Large (the default). The menu displays all items in a list." ] }, { "type": "paragraph", "text": "For developer guidance, see preferredElementSize." }, { "type": "paragraph", "text": "Choose a small or medium menu layout when it can help streamline people’s choices. Consider using the medium layout if your app has three important actions that people often want to perform. For example, Notes uses the medium layout to give people a quick way to perform the Scan, Lock, and Pin actions. Use the small layout only for closely related actions that typically appear as a group, such as Bold, Italic, Underline, and Strikethrough. For each action, use a recognizable symbol that helps people identify the action without a label." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In visionOS, a menu can display items using the small or large layout styles that iOS and iPadOS define (for guidance, see iOS, iPadOS). You can present a menu in your app or game from 3D content using a SwiftUI view. To ensure that your menu is always visible to people, even when other content occludes it, you can apply a breakthrough effect. As in macOS, an open menu in a visionOS window can appear outside of the window’s boundaries." }, { "type": "paragraph", "text": "Prefer displaying a menu near the content it controls. Because people need to look at a menu item before tapping it, they might miss the item’s effect if the content it controls is too far away." }, { "type": "paragraph", "text": "Prefer the subtle breakthrough effect in most cases. This effect blends the presentation with its surrounding content, to maintain legibility and usability while preserving the depth and context of the scene. When you select automatic for the breakthrough effect of a menu that overlaps with 3D content, the system applies subtle by default. You can use prominent if it’s important to display a menu prominently over the entire scene in your app or game, but this can disrupt the experience for people and potentially cause discomfort. Alternatively, you can use none to fully occlude your menu behind other 3D content — for example, in a puzzle game that requires people to navigate around barriers — but this may make it difficult for people to see and access the menu." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Pop-up buttons" }, { "type": "paragraph", "text": "Pull-down buttons" }, { "type": "paragraph", "text": "Context menus" }, { "type": "paragraph", "text": "The menu bar" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Menu — SwiftUI" }, { "type": "paragraph", "text": "Menus and shortcuts — UIKit" }, { "type": "paragraph", "text": "Menus — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Added guidance for presenting menus with breakthrough effects in visionOS." ], [ "July 28, 2025", "Added guidance for representing menu items with icons." ], [ "June 10, 2024", "Added guidance for in-game menus and included game-specific examples." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "September 14, 2022", "Added guidelines for using the small, medium, and large menu layouts in iPadOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "pop-up button", "url": "/design/human-interface-guidelines/pop-up-buttons" }, { "title": "pull-down button", "url": "/design/human-interface-guidelines/pull-down-buttons" }, { "title": "context menu", "url": "/design/human-interface-guidelines/context-menus" }, { "title": "menu bar", "url": "/design/human-interface-guidelines/the-menu-bar" }, { "title": "Labels", "url": "/design/human-interface-guidelines/menus#Labels" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/menus#visionOS" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/menus#iOS-iPadOS" }, { "title": "Toggled items", "url": "/design/human-interface-guidelines/menus#Toggled-items" }, { "title": "Icons", "url": "/design/human-interface-guidelines/menus#Icons" }, { "title": "Standard icons", "url": "/design/human-interface-guidelines/icons#Standard-icons" }, { "title": "Organization", "url": "/design/human-interface-guidelines/menus#Organization" }, { "title": "Submenus", "url": "/design/human-interface-guidelines/menus#Submenus" }, { "title": "In-game menus", "url": "/design/human-interface-guidelines/menus#In-game-menus" }, { "title": "settings", "url": "https://developer.apple.com/design/human-interface-guidelines/settings" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Touch controls", "url": "/design/human-interface-guidelines/game-controls#Touch-controls" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/menus#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/menus#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/menus#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/menus#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/menus#Change-log" } ], "image_count": 0 }, { "title": "Motion", "url": "https://developer.apple.com/design/human-interface-guidelines/motion", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Many system components automatically include motion, letting you offer familiar and consistent experiences throughout your app or game. System components might also adjust their motion in response to factors like accessibility settings or different input methods. For example, the movement of Liquid Glass responds to direct touch interaction with greater emphasis to reinforce the feeling of a tactile experience, but produces a more subdued effect when a person interacts using a trackpad." }, { "type": "paragraph", "text": "If you design custom motion, follow the guidelines below." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Add motion purposefully, supporting the experience without overshadowing it. Don’t add motion for the sake of adding motion. Gratuitous or excessive animation can distract people and may make them feel disconnected or physically uncomfortable." }, { "type": "paragraph", "text": "Make motion optional. Not everyone can or wants to experience the motion in your app or game, so it’s essential to avoid using it as the only way to communicate important information. To help everyone enjoy your app or game, supplement visual feedback by also using alternatives like haptics and audio to communicate." } ] }, { "heading": "Providing feedback", "level": 2, "content": [ { "type": "paragraph", "text": "Strive for realistic feedback motion that follows people’s gestures and expectations. In nongame apps, accurate, realistic motion can help people understand how something works, but feedback motion that doesn’t make sense can make them feel disoriented. For example, if someone reveals a view by sliding it down from the top, they don’t expect to dismiss the view by sliding it to the side." }, { "type": "paragraph", "text": "Aim for brevity and precision in feedback animations. When animated feedback is brief and precise, it tends to feel lightweight and unobtrusive, and it can often convey information more effectively than prominent animation. For example, when a game displays a succinct animation that’s precisely tied to a successful action, players can instantly get the message without being distracted from their gameplay. Another example is in visionOS: When people tap a panorama in Photos, it quickly and smoothly expands to fill the space in front of them, helping them track the transition without making them wait to enjoy the content." }, { "type": "paragraph", "text": "In apps, generally avoid adding motion to UI interactions that occur frequently. The system already provides subtle animations for interactions with standard interface elements. For a custom element, you generally want to avoid making people spend extra time paying attention to unnecessary motion every time they interact with it." }, { "type": "paragraph", "text": "Let people cancel motion. As much as possible, don’t make people wait for an animation to complete before they can do anything, especially if they have to experience the animation more than once." }, { "type": "paragraph", "text": "Consider using animated symbols where it makes sense. When you use SF Symbols 5 or later, you can apply animations to SF Symbols or custom symbols. For guidance, see Animations." } ] }, { "heading": "Leveraging platform capabilities", "level": 2, "content": [ { "type": "paragraph", "text": "Make sure your game’s motion looks great by default on each platform you support. In most games, maintaining a consistent frame rate of 30 to 60 fps typically results in a smooth, visually appealing experience. For each platform you support, use the device’s graphics capabilities to enable default settings that let people enjoy your game without first having to change those settings." }, { "type": "paragraph", "text": "Let people customize the visual experience of your game to optimize performance or battery life. For example, consider letting people switch between power modes when the system detects the presence of an external power source." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In addition to subtly communicating context, drawing attention to information, and enriching immersive experiences, motion in visionOS can combine with depth to provide essential feedback when people look at interactive elements. Because motion is likely to be a large part of your visionOS experience, it’s crucial to avoid causing distraction, confusion, or discomfort." }, { "type": "paragraph", "text": "As much as possible, avoid displaying motion at the edges of a person’s field of view. People can be particularly sensitive to motion that occurs in their peripheral vision: in addition to being distracting, such motion can even cause discomfort because it can make people feel like they or their surroundings are moving. If you need to show an object moving in the periphery during an immersive experience, make sure the object’s brightness level is similar to the rest of the visible content." }, { "type": "paragraph", "text": "Help people remain comfortable when showing the movement of large virtual objects. If an object is large enough to fill a lot of the field of view, occluding most or all of passthrough, people can naturally perceive it as being part of their surroundings. To help people perceive the object’s movement without making them think that they or their surroundings are moving, you can increase the object’s translucency, helping people see through it, or lower its contrast to make its motion less noticeable." }, { "type": "note", "text": "NotePeople can experience discomfort even when they’re the ones moving a large virtual object, such as a window. Although adjusting translucency and contrast can help in this scenario, consider also keeping a window’s size fairly small." }, { "type": "paragraph", "text": "Consider using fades when you need to relocate an object. When an object moves from one location to another, people naturally watch the movement. If such movement doesn’t communicate anything useful to people, you can fade the object out before moving it and fade it back in after it’s in the new location." }, { "type": "paragraph", "text": "In general, avoid letting people rotate a virtual world. When a virtual world rotates, the experience typically upsets people’s sense of stability, even when they control the rotation and the movement is subtle. Instead, consider using instantaneous directional changes during a quick fade-out." }, { "type": "paragraph", "text": "Consider giving people a stationary frame of reference. It can be easier for people to handle visual movement when it’s contained within an area that doesn’t move. In contrast, if the entire surrounding area appears to move — for example, in a game that automatically moves a player through space — people can feel unwell." }, { "type": "paragraph", "text": "Avoid showing objects that oscillate in a sustained way. In particular, you want to avoid showing an oscillation that has a frequency of around 0.2 Hz because people can be very sensitive to this frequency. If you need to show objects oscillating, aim to keep the amplitude low and consider making the content translucent." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "SwiftUI provides a powerful and streamlined way to add motion to your app. If you need to use WatchKit to animate layout and appearance changes — or create animated image sequences — see WKInterfaceImage." }, { "type": "note", "text": "NoteAll layout- and appearance-based animations automatically include built-in easing that plays at the start and end of the animation. You can’t turn off or customize easing." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Feedback" }, { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Spatial layout" }, { "type": "paragraph", "text": "Immersive experiences" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Animating views and transitions — SwiftUI" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 9, 2025", "Added guidance for Liquid Glass." ], [ "June 10, 2024", "Added game-specific examples and enhanced guidance for using motion in games." ], [ "February 2, 2024", "Enhanced guidance for minimizing peripheral motion in visionOS apps." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/motion#Best-practices" }, { "title": "haptics", "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics" }, { "title": "audio", "url": "https://developer.apple.com/design/human-interface-guidelines/playing-audio" }, { "title": "Providing feedback", "url": "/design/human-interface-guidelines/motion#Providing-feedback" }, { "title": "Animations", "url": "/design/human-interface-guidelines/sf-symbols#Animations" }, { "title": "Leveraging platform capabilities", "url": "/design/human-interface-guidelines/motion#Leveraging-platform-capabilities" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/motion#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/motion#visionOS" }, { "title": "depth", "url": "/design/human-interface-guidelines/spatial-layout#Depth" }, { "title": "field of view", "url": "/design/human-interface-guidelines/spatial-layout#Field-of-view" }, { "title": "passthrough", "url": "/design/human-interface-guidelines/immersive-experiences#Immersion-and-passthrough" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/motion#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/motion#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/motion#Related" }, { "title": "Feedback", "url": "/design/human-interface-guidelines/feedback" }, { "title": "Spatial layout", "url": "/design/human-interface-guidelines/spatial-layout" }, { "title": "Immersive experiences", "url": "/design/human-interface-guidelines/immersive-experiences" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/motion#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/motion#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/motion#Change-log" } ], "image_count": 0 }, { "title": "Ornaments", "url": "https://developer.apple.com/design/human-interface-guidelines/ornaments", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "An ornament floats in a plane that’s parallel to its associated window and slightly in front of it along the z-axis. If the associated window moves, the ornament moves with it, maintaining its relative position; if the window’s contents scroll, the controls or information in the ornament remain unchanged." }, { "type": "paragraph", "text": "Ornaments can appear on any edge of a window and can contain UI components like buttons, segmented controls, and other views. The system uses ornaments to create and manage components like toolbars, tab bars, and video playback controls; you can use an ornament to create a custom component." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Consider using an ornament to present frequently needed controls or information in a consistent location that doesn’t clutter the window. Because an ornament stays close to its window, people always know where to find it. For example, Music uses an ornament to offer Now Playing controls, ensuring that these controls remain in a predictable location that’s easy to find." }, { "type": "paragraph", "text": "In general, keep an ornament visible. It can make sense to hide an ornament when people dive into a window’s content — for example, when they watch a video or view a photo — but in most cases, people appreciate having consistent access to an ornament’s controls." }, { "type": "paragraph", "text": "If you need to display multiple ornaments, prioritize the overall visual balance of the window. Ornaments help elevate important actions, but they can sometimes distract from your content. When necessary, consider constraining the total number of ornaments to avoid increasing a window’s visual weight and making your app feel more complicated. If you decide to remove an ornament, you can relocate its elements into the main window." }, { "type": "paragraph", "text": "Aim to keep an ornament’s width the same or narrower than the width of the associated window. If an ornament is wider than its window, it can interfere with a tab bar or other vertical content on the window’s side." }, { "type": "paragraph", "text": "Consider using borderless buttons in an ornament. By default, an ornament’s background is glass, so if you place a button directly on the background, it may not need a visible border. When people look at a borderless button in an ornament, the system automatically applies the hover affect to it (for guidance, see Eyes)." }, { "type": "paragraph", "text": "Use system-provided toolbars and tab bars unless you need to create custom components. In visionOS, toolbars and tab bars automatically appear as ornaments, so you don’t need to use an ornament to create these components. For developer guidance, see Toolbars and TabView." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "Not supported in iOS, iPadOS, macOS, tvOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Layout" }, { "type": "paragraph", "text": "Toolbars" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "ornament(visibility:attachmentAnchor:contentAlignment:ornament:) — SwiftUI" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "February 2, 2024", "Added guidance on using multiple ornaments." ], [ "December 5, 2023", "Removed a statement about using ornaments to present supplementary items." ], [ "June 21, 2023", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "toolbars", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "tab bars", "url": "/design/human-interface-guidelines/tab-bars" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/ornaments#Best-practices" }, { "title": "glass", "url": "/design/human-interface-guidelines/materials#visionOS" }, { "title": "Eyes", "url": "/design/human-interface-guidelines/eyes" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/ornaments#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/ornaments#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/ornaments#Related" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/ornaments#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/ornaments#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/ornaments#Change-log" } ], "image_count": 0 }, { "title": "Privacy", "url": "https://developer.apple.com/design/human-interface-guidelines/privacy", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "People use their devices in very personal ways and they expect apps to help them preserve their privacy." }, { "type": "paragraph", "text": "When you submit a new or updated app, you must provide details about your privacy practices and the privacy-relevant data you collect so the App Store can display the information on your product page. (You can manage this information at any time in App Store Connect.) People use the privacy details on your product page to make an informed decision before they download your app. To learn more, see App privacy details on the App Store." }, { "type": "paragraph", "text": "An app’s App Store product page helps people understand the app’s privacy practices before they download it." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Request access only to data that you actually need. Asking for more data than a feature needs — or asking for data before a person shows interest in the feature — can make it hard for people to trust your app. Give people precise control over their data by making your permission requests as specific as possible." }, { "type": "paragraph", "text": "Be transparent about how your app collects and uses people’s data. People are less likely to be comfortable sharing data with your app if they don’t understand exactly how you plan to use it. Always respect people’s choices to use system features like Hide My Email and Mail Privacy Protection, and be sure you understand your obligations with regard to app tracking. To learn more about Apple privacy features, see Privacy; for developer guidance, see User privacy and data use." }, { "type": "paragraph", "text": "Process data on the device where possible. In iOS, for example, you can take advantage of the Apple Neural Engine and custom CreateML models to process the data right on the device, helping you avoid lengthy and potentially risky round trips to a remote server." }, { "type": "paragraph", "text": "Adopt system-defined privacy protections and follow security best practices. For example, in iOS 15 and later, you can rely on CloudKit to provide encryption and key management for additional data types, like strings, numbers, and dates." } ] }, { "heading": "Requesting permission", "level": 2, "content": [ { "type": "paragraph", "text": "Here are several examples of the things you must request permission to access:" }, { "type": "list", "items": [ "Personal data, including location, health, financial, contact, and other personally identifying information", "User-generated content like emails, messages, calendar data, contacts, gameplay information, Apple Music activity, HomeKit data, and audio, video, and photo content", "Protected resources like Bluetooth peripherals, home automation features, Wi-Fi connections, and local networks", "Device capabilities like camera and microphone", "In a visionOS app running in a Full Space, ARKit data, such as hand tracking, plane estimation, image anchoring, and world tracking", "The device’s advertising identifier, which supports app tracking" ] }, { "type": "paragraph", "text": "The system provides a standard alert that lets people view each request you make. You supply copy that describes why your app needs access, and the system displays your description in the alert. People can also view the description — and update their choice — in Settings > Privacy." }, { "type": "paragraph", "text": "Request permission only when your app clearly needs access to the data or resource. It’s natural for people to be suspicious of a request for personal information or access to a device capability, especially if there’s no obvious need for it. Ideally, wait to request permission until people actually use an app feature that requires access. For example, you can use the location button to give people a way to share their location after they indicate interest in a feature that needs that information." }, { "type": "paragraph", "text": "Avoid requesting permission at launch unless the data or resource is required for your app to function. People are less likely to be bothered by a launch-time request when it’s obvious why you’re making it. For example, people understand that a navigation app needs access to their location before they can benefit from it. Similarly, before people can play a visionOS game that lets them bounce virtual objects off walls in their surroundings, they need to permit the game to access information about their surroundings." }, { "type": "paragraph", "text": "Write copy that clearly describes how your app uses the ability, data, or resource you’re requesting. The standard alert displays your copy (called a purpose string or usage description string) after your app name and before the buttons people use to grant or deny their permission. Aim for a brief, complete sentence that’s straightforward, specific, and easy to understand. Use sentence case, avoid passive voice, and include a period at the end. For developer guidance, see Requesting access to protected resources and App Tracking Transparency." }, { "type": "table", "rows": [ [ "", "Example purpose string", "Notes" ], [ "", "The app records during the night to detect snoring sounds.", "An active sentence that clearly describes how and why the app collects the data." ], [ "", "Microphone access is needed for a better experience.", "A passive sentence that provides a vague, undefined justification." ], [ "", "Turn on microphone access.", "An imperative sentence that doesn’t provide any justification." ] ] }, { "type": "paragraph", "text": "Here are several examples of the standard system alert:" } ] }, { "heading": "Pre-alert screens, windows, or views", "level": 3, "content": [ { "type": "paragraph", "text": "Ideally, the current context helps people understand why you’re requesting their permission. If it’s essential to provide additional details, you can display a custom screen or window before the system alert appears. The following guidelines apply to custom views that display before system alerts that request permission to access protected data and resources, including camera, microphone, location, contact, calendar, and tracking." }, { "type": "paragraph", "text": "Include only one button and make it clear that it opens the system alert. People can feel manipulated when a custom screen or window also includes a button that doesn’t open the alert because the experience diverts them from making their choice. Another type of manipulation is using a term like “Allow” to title the custom screen’s button. If the custom button seems similar in meaning and visual weight to the allow button in the alert, people can be more likely to choose the alert’s allow button without meaning to. Use a term like “Continue” or “Next” to title the single button in your custom screen or window, clarifying that its action is to open the system alert." }, { "type": "paragraph", "text": "Don’t include additional actions in your custom screen or window. For example, don’t provide a way for people to leave the screen or window without viewing the system alert — like offering an option to close or cancel." }, { "type": "paragraph", "text": "Don’t include an option to cancel." }, { "type": "paragraph", "text": "Don’t include an option to close the view." } ] }, { "heading": "Tracking requests", "level": 3, "content": [ { "type": "paragraph", "text": "App tracking is a sensitive issue. In some cases, it might make sense to display a custom screen or window that describes the benefits of tracking. If you want to perform app tracking as soon as people launch your app, you must display the system-provided alert before you collect any tracking data." }, { "type": "paragraph", "text": "Never precede the system-provided alert with a custom screen or window that could confuse or mislead people. People sometimes tap quickly to dismiss alerts without reading them. A custom messaging screen, window, or view that takes advantage of such behaviors to influence choices will lead to rejection by App Store review." }, { "type": "paragraph", "text": "There are several prohibited custom-screen designs that will cause rejection. Some examples are offering incentives, displaying a screen or window that looks like a request, displaying an image of the alert, and annotating the screen behind the alert (as shown below). To learn more, see App Review Guidelines: 5.1.1 (iv)." }, { "type": "paragraph", "text": "Don’t offer incentives for granting the request. You can’t offer people compensation for granting their permission, and you can’t withhold functionality or content or make your app unusable until people allow you to track them." }, { "type": "paragraph", "text": "Don’t display a custom screen that mirrors the functionality of the system alert. In particular, don’t create a button title that uses “Allow” or similar terms, because people don’t allow anything in a pre-alert screen." }, { "type": "paragraph", "text": "Don’t show an image of the standard alert and modify it in any way." }, { "type": "paragraph", "text": "Don’t add a visual cue that draws people’s attention to the system alert’s Allow buttons." } ] }, { "heading": "Location button", "level": 2, "content": [ { "type": "paragraph", "text": "In iOS, iPadOS, and watchOS, Core Location provides a button so people can grant your app temporary authorization to access their location at the moment a task needs it. A location button’s appearance can vary to match your app’s UI and it always communicates the action of location sharing in a way that’s instantly recognizable." }, { "type": "paragraph", "text": "The first time people open your app and tap a location button, the system displays a standard alert. The alert helps people understand how using the button limits your app’s access to their location, and reminds them of the location indicator that appears when sharing starts." }, { "type": "paragraph", "text": "After people confirm their understanding of the button’s action, simply tapping the location button gives your app one-time permission to access their location. Although each one-time authorization expires when people stop using your app, they don’t need to reconfirm their understanding of the button’s behavior." }, { "type": "note", "text": "NoteIf your app has no authorization status, tapping the location button has the same effect as when a person chooses Allow Once in the standard alert. If people previously chose While Using the App, tapping the location button doesn’t change your app’s status. For developer guidance, see LocationButton (SwiftUI) and CLLocationButton (Swift)." }, { "type": "paragraph", "text": "Consider using the location button to give people a lightweight way to share their location for specific app features. For example, your app might help people attach their location to a message or post, find a store, or identify a building, plant, or animal they’ve encountered in their location. If you know that people often grant your app Allow Once permission, consider using the location button to help them benefit from sharing their location without having to repeatedly interact with the alert." }, { "type": "paragraph", "text": "Consider customizing the location button to harmonize with your UI. Specifically, you can:" }, { "type": "list", "items": [ "Choose the system-provided title that works best with your feature, such as “Current Location” or “Share My Current Location.”", "Choose the filled or outlined location glyph.", "Select a background color and a color for the title and glyph.", "Adjust the button’s corner radius." ] }, { "type": "paragraph", "text": "To help people recognize and trust location buttons, you can’t customize the button’s other visual attributes. The system also ensures a location button remains legible by warning you about problems like low-contrast color combinations or too much translucency. In addition to fixing such problems, you’re responsible for making sure the text fits in the button — for example, button text needs to fit without truncation at all accessibility text sizes and when translated into other languages." }, { "type": "important", "text": "ImportantIf the system identifies consistent problems with your customized location button, it won’t give your app access to the device location when people tap it. Although such a button can perform other app-specific actions, people may lose trust in your app if your location button doesn’t work as they expect." } ] }, { "heading": "Protecting data", "level": 2, "content": [ { "type": "paragraph", "text": "Protecting people’s information is paramount. Give people confidence in your app’s security and help preserve their privacy by taking advantage of system-provided security technologies when you need to store information locally, authorize people for specific operations, and transport information across a network." }, { "type": "paragraph", "text": "Here are some high-level guidelines." }, { "type": "paragraph", "text": "Avoid relying solely on passwords for authentication. Where possible, use passkeys to replace passwords. If you need to continue using passwords for authentication, augment security by requiring two-factor authentication (for developer guidance, see Securing Logins with iCloud Keychain Verification Codes). To further protect access to apps that people keep logged in on their device, use biometric identification like Face ID, Optic ID, or Touch ID. For developer guidance, see Local Authentication." }, { "type": "paragraph", "text": "Store sensitive information in a keychain. A keychain provides a secure, predictable user experience when handling someone’s private information. For developer guidance, see Keychain services." }, { "type": "paragraph", "text": "Never store passwords or other secure content in plain-text files. Even if you restrict access using file permissions, sensitive information is much safer in an encrypted keychain." }, { "type": "paragraph", "text": "Avoid inventing custom authentication schemes. If your app requires authentication, prefer system-provided features like passkeys, Sign in with Apple or Password AutoFill. For related guidance, see Managing accounts." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, tvOS, or watchOS." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "Sign your app with a valid Developer ID. If you choose to distribute your app outside the store, signing your app with Developer ID identifies you as an Apple developer and confirms that your app is safe to use. For developer guidance, see Xcode Help." }, { "type": "paragraph", "text": "Protect people’s data with app sandboxing. Sandboxing provides your app with access to system resources and user data while protecting it from malware. All apps submitted to the Mac App Store require sandboxing. For developer guidance, see Configuring the macOS App Sandbox." }, { "type": "paragraph", "text": "Avoid making assumptions about who is signed in. Because of fast user switching, multiple people may be active on the same system." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "By default, visionOS uses ARKit algorithms to handle features like persistence, world mapping, segmentation, matting, and environment lighting. These algorithms are always running, allowing apps and games to automatically benefit from ARKit while in the Shared Space." }, { "type": "paragraph", "text": "ARKit doesn’t send data to apps in the Shared Space; to access ARKit APIs, your app must open a Full Space. Additionally, features like Plane Estimation, Scene Reconstruction, Image Anchoring, and Hand Tracking require people’s permission to access any information. For developer guidance, see Setting up access to ARKit data." }, { "type": "paragraph", "text": "In visionOS, user input is private by design. The system automatically displays hover effects when people look at interactive components you create using SwiftUI or RealityKit, giving people the visual feedback they need without exposing where they’re looking before they tap. For guidance, see Eyes and Gestures > visionOS." }, { "type": "paragraph", "text": "Developer access to device cameras works differently in visionOS than it does in other platforms. Specifically, the back camera provides blank input and is only available as a compatibility convenience; the front camera provides input for spatial Personas, but only after people grant their permission. If the iOS or iPadOS app you’re bringing to visionOS includes a feature that needs camera access, remove it or replace it with an option for people to import content instead. For developer guidance, see Making your existing app compatible with visionOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Entering data" }, { "type": "paragraph", "text": "Onboarding" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Requesting access to protected resources — UIKit" }, { "type": "paragraph", "text": "Security" }, { "type": "paragraph", "text": "Requesting authorization to use location services — CoreLocation" }, { "type": "paragraph", "text": "App Tracking Transparency" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 21, 2023", "Consolidated guidance into new page and updated for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/privacy#Best-practices" }, { "title": "Requesting permission", "url": "/design/human-interface-guidelines/privacy#Requesting-permission" }, { "title": "location button", "url": "/design/human-interface-guidelines/privacy#Location-button" }, { "title": "Pre-alert screens, windows, or views", "url": "/design/human-interface-guidelines/privacy#Pre-alert-screens-windows-or-views" }, { "title": "Tracking requests", "url": "/design/human-interface-guidelines/privacy#Tracking-requests" }, { "title": "Protecting data", "url": "/design/human-interface-guidelines/privacy#Protecting-data" }, { "title": "Sign in with Apple", "url": "/design/human-interface-guidelines/sign-in-with-apple" }, { "title": "Managing accounts", "url": "/design/human-interface-guidelines/managing-accounts" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/privacy#Platform-considerations" }, { "title": "macOS", "url": "/design/human-interface-guidelines/privacy#macOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/privacy#visionOS" }, { "title": "Eyes", "url": "/design/human-interface-guidelines/eyes" }, { "title": "Gestures > visionOS", "url": "/design/human-interface-guidelines/gestures#visionOS" }, { "title": "spatial Personas", "url": "/design/human-interface-guidelines/shareplay#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/privacy#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/privacy#Related" }, { "title": "Entering data", "url": "/design/human-interface-guidelines/entering-data" }, { "title": "Onboarding", "url": "/design/human-interface-guidelines/onboarding" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/privacy#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/privacy#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/privacy#Change-log" } ], "image_count": 0 }, { "title": "Right to left", "url": "https://developer.apple.com/design/human-interface-guidelines/right-to-left", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When people choose a language for their device — or just your app or game — they expect the interface to adapt in various ways (to learn more, see Localization)." }, { "type": "paragraph", "text": "System-provided UI frameworks support right-to-left (RTL) by default, allowing system-provided UI components to flip automatically in the RTL context. If you use system-provided elements and standard layouts, you might not need to make any changes to your app’s automatically reversed interface." }, { "type": "paragraph", "text": "If you want to fine-tune your layout or enhance specific localizations to adapt to different currencies, numerals, or mathematical symbols that can occur in various locales in countries that use RTL languages, follow these guidelines." } ] }, { "heading": "Text alignment", "level": 2, "content": [ { "type": "paragraph", "text": "Adjust text alignment to match the interface direction, if the system doesn’t do so automatically. For example, if you left-align text with content in the left-to-right (LTR) context, right-align the text to match the content’s mirrored position in the RTL context." }, { "type": "paragraph", "text": "Left-aligned text in the LTR context" }, { "type": "paragraph", "text": "Right-aligned content in the RTL context" }, { "type": "paragraph", "text": "Align a paragraph based on its language, not on the current context. When the alignment of a paragraph — defined as three or more lines of text — doesn’t match its language, it can be difficult to read. For example, right-aligning a paragraph that consists of LTR text can make the beginning of each line difficult to see. To improve readability, continue aligning one- and two-line text blocks to match the reading direction of the current context, but align a paragraph to match its language." }, { "type": "paragraph", "text": "A left-aligned paragraph in the RTL context" }, { "type": "paragraph", "text": "A right-aligned paragraph in the RTL context" }, { "type": "paragraph", "text": "Use a consistent alignment for all text items in a list. To ensure a comfortable reading and scanning experience, reverse the alignment of all items in a list, including items that are displayed in a different script." }, { "type": "paragraph", "text": "Right-aligned content in the RTL context" }, { "type": "paragraph", "text": "Mixed alignment in the RTL content" } ] }, { "heading": "Numbers and characters", "level": 2, "content": [ { "type": "paragraph", "text": "Different RTL languages can use different number systems. For example, Hebrew text uses Western Arabic numerals, whereas Arabic text might use either Western or Eastern Arabic numerals. The use of Western and Eastern Arabic numerals varies among countries and regions and even among areas within the same country or region." }, { "type": "paragraph", "text": "If your app covers mathematical concepts or other number-centric topics, it’s a good idea to identify the appropriate way to display such information in each locale you support. In contrast, apps that don’t address number-related topics can generally rely on system-provided number representations." }, { "type": "paragraph", "text": "Western Arabic numerals" }, { "type": "paragraph", "text": "Eastern Arabic numerals" }, { "type": "paragraph", "text": "Don’t reverse the order of numerals in a specific number. Regardless of the current language or the surrounding content, the digits in a specific number — such as “541,” a phone number, or a credit card number — always appear in the same order." }, { "type": "paragraph", "text": "Latin" }, { "type": "paragraph", "text": "Hebrew" }, { "type": "paragraph", "text": "Arabic (Western Arabic numerals)" }, { "type": "paragraph", "text": "Arabic (Eastern Arabic numerals)" }, { "type": "paragraph", "text": "Reverse the order of numerals that show progress or a counting direction; never flip the numerals themselves. Controls like progress bars, sliders, and rating controls often include numerals to clarify their meaning. If you use numerals in this way, be sure to reverse the order of the numerals to match the direction of the flipped control. Also reverse a sequence of numerals if you use the sequence to communicate a specific order." }, { "type": "paragraph", "text": "Latin" }, { "type": "paragraph", "text": "Arabic (Eastern Arabic numerals)" }, { "type": "paragraph", "text": "Hebrew" }, { "type": "paragraph", "text": "Arabic (Western Arabic numerals)" } ] }, { "heading": "Controls", "level": 2, "content": [ { "type": "paragraph", "text": "Flip controls that show progress from one value to another. Because people tend to view forward progress as moving in the same direction as the language they read, it makes sense to flip controls like sliders and progress indicators in the RTL context. When you do this, also be sure to reverse the positions of the accompanying glyphs or images that depict the beginning and ending values of the control." }, { "type": "paragraph", "text": "A directional control in the LTR context" }, { "type": "paragraph", "text": "A directional control in the RTL context" }, { "type": "paragraph", "text": "Flip controls that help people navigate or access items in a fixed order. For example, in the RTL context, a back button must point to the right so the flow of screens matches the reading order of the RTL language. Similarly, next or previous buttons that let people access items in an ordered list need to flip in the RTL context to match the reading order." }, { "type": "paragraph", "text": "Preserve the direction of a control that refers to an actual direction or points to an onscreen area. For example, if you provide a control that means “to the right,” it must always point right, regardless of the current context." }, { "type": "paragraph", "text": "Visually balance adjacent Latin and RTL scripts when necessary. In buttons, labels, and titles, Arabic or Hebrew text can appear too small when next to uppercased Latin text, because Arabic and Hebrew don’t include uppercase letters. To visually balance Arabic or Hebrew text with Latin text that uses all capitals, it often works well to increase the RTL font size by about 2 points." }, { "type": "paragraph", "text": "Arabic and Hebrew text can look too small next to uppercased Latin text of the same font size." }, { "type": "paragraph", "text": "You can slightly increase the font size of Arabic and Hebrew text to visually balance uppercased Latin text." } ] }, { "heading": "Images", "level": 2, "content": [ { "type": "paragraph", "text": "Avoid flipping images like photographs, illustrations, and general artwork. Flipping an image often changes the image’s meaning; flipping a copyrighted image could be a violation. If an image’s content is strongly connected to reading direction, consider creating a new version of the image instead of flipping the original." }, { "type": "paragraph", "text": "Reverse the positions of images when their order is meaningful. For example, if you display multiple images in a specific order like chronological, alphabetical, or favorite, reverse their positions to preserve the order’s meaning in the RTL context." }, { "type": "paragraph", "text": "Items with meaningful positions in the LTR context" }, { "type": "paragraph", "text": "Items with meaningful positions in the RTL context" } ] }, { "heading": "Interface icons", "level": 2, "content": [ { "type": "paragraph", "text": "When you use SF Symbols to supply interface icons for your app, you get variants for the RTL context and localized symbols for Arabic and Hebrew, among other languages. If you create custom symbols, you can specify their directionality. For developer guidance, see Creating custom symbol images for your app." }, { "type": "paragraph", "text": "LTR variants of directional symbols" }, { "type": "paragraph", "text": "RTL variants of directional symbols" }, { "type": "paragraph", "text": "Flip interface icons that represent text or reading direction. For example, if an interface icon uses left-aligned bars to represent text in the LTR context, right-align the bars in the RTL context." }, { "type": "paragraph", "text": "LTR variant of a symbol that represents text" }, { "type": "paragraph", "text": "RTL variant of a symbol that represents text" }, { "type": "paragraph", "text": "Consider creating a localized version of an interface icon that displays text. Some interface icons include letters or words to help communicate a script-related concept, like font-size choice or a signature. If you have a custom interface icon that needs to display actual text, consider creating a localized version. For example, SF Symbols offers different versions of the signature, rich-text, and I-beam pointer symbols for use with Latin, Hebrew, and Arabic text, among others." }, { "type": "paragraph", "text": "Latin" }, { "type": "paragraph", "text": "Hebrew" }, { "type": "paragraph", "text": "Arabic" }, { "type": "paragraph", "text": "If you have a custom interface icon that uses letters or words to communicate a concept unrelated to reading or writing, consider designing an alternative image that doesn’t use text." }, { "type": "paragraph", "text": "Flip an interface icon that shows forward or backward motion. When something moves in the same direction that people read, they typically interpret that direction as forward; when something moves in the opposite direction, people tend to interpret the direction as backward. An interface icon that depicts an object moving forward or backward needs to flip in the RTL context to preserve the meaning of the motion. For example, an icon that represents a speaker typically shows sound waves emanating forward from the speaker. In the LTR context, the sound waves come from the left, so in the RTL context, the icon needs to flip to show the waves coming from the right." }, { "type": "paragraph", "text": "LTR variant of a symbol that depicts forward motion" }, { "type": "paragraph", "text": "RTL variant of a symbol that depicts forward motion" }, { "type": "paragraph", "text": "Don’t flip logos or universal signs and marks. Displaying a flipped logo confuses people and can have legal repercussions. Always display a logo in its original form, even if it includes text. People expect universal symbols and marks like the checkmark to have a consistent appearance, so avoid flipping them." }, { "type": "paragraph", "text": "A logo" }, { "type": "paragraph", "text": "A universal symbol or mark" }, { "type": "paragraph", "text": "In general, avoid flipping interface icons that depict real-world objects. Unless you use the object to indicate directionality, it’s best to avoid flipping an icon that represents a familiar item. For example, clocks work the same everywhere, so a traditional clock interface icon needs to look the same regardless of language direction. Some interface icons might seem to reference language or reading direction because they represent items that are slanted for right-handed use. However, most people are right-handed, so flipping an icon that shows a right-handed tool isn’t necessary and might be confusing." }, { "type": "paragraph", "text": "Before merely flipping a complex custom interface icon, consider its individual components and the overall visual balance. In some cases, a component — like a badge, slash, or magnifying glass — needs to adhere to a visual design language regardless of localization. For example, SF Symbols maintains visual consistency by using the same backslash to represent the prohibition or negation of a symbol’s meaning in both LTR and RTL versions." }, { "type": "paragraph", "text": "LTR variant of a symbol that includes a backslash" }, { "type": "paragraph", "text": "RTL variant of a symbol that includes a backslash" }, { "type": "paragraph", "text": "In other cases, you might need to flip a component (or its position) to ensure the localized version of the icon still makes sense. For example, if a badge represents the actual UI that people see in your app, it needs to flip if your UI flips. Alternatively, if a badge modifies the meaning of an interface icon, consider whether flipping the badge preserves both the modified meaning and the overall visual balance of the icon. In the images shown below, the badge doesn’t depict an object in the UI, but keeping it in the top-right corner visually unbalances the cart." }, { "type": "paragraph", "text": "If your custom interface icon includes a component that can imply handedness, like a tool, consider preserving the orientation of the tool while flipping the base image if necessary." }, { "type": "paragraph", "text": "LTR variant of a symbol that depicts a tool" }, { "type": "paragraph", "text": "RTL variant of a symbol that depicts a tool" } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Layout" }, { "type": "paragraph", "text": "Inclusion" }, { "type": "paragraph", "text": "SF Symbols" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Localization" }, { "type": "paragraph", "text": "Preparing views for localization — SwiftUI" } ] } ], "platforms": [], "related": [ { "title": "Text alignment", "url": "/design/human-interface-guidelines/right-to-left#Text-alignment" }, { "title": "Numbers and characters", "url": "/design/human-interface-guidelines/right-to-left#Numbers-and-characters" }, { "title": "Controls", "url": "/design/human-interface-guidelines/right-to-left#Controls" }, { "title": "Images", "url": "/design/human-interface-guidelines/right-to-left#Images" }, { "title": "Interface icons", "url": "/design/human-interface-guidelines/right-to-left#Interface-icons" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/right-to-left#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/right-to-left#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/right-to-left#Related" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/right-to-left#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/right-to-left#Videos" } ], "image_count": 0 }, { "title": "SF Symbols", "url": "https://developer.apple.com/design/human-interface-guidelines/sf-symbols", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "You can use a symbol to convey an object or concept wherever interface icons can appear, such as in toolbars, tab bars, context menus, and within text." }, { "type": "paragraph", "text": "Availability of individual symbols and features varies based on the version of the system you’re targeting. Symbols and symbol features introduced in a given year aren’t available in earlier operating systems." }, { "type": "paragraph", "text": "Visit SF Symbols to download the app and browse the full set of symbols. Be sure to understand the terms and conditions for using SF Symbols, including the prohibition against using symbols — or images that are confusingly similar — in app icons, logos, or any other trademarked use. For developer guidance, see Configuring and displaying symbol images in your UI." } ] }, { "heading": "Rendering modes", "level": 2, "content": [ { "type": "paragraph", "text": "SF Symbols provides four rendering modes — monochrome, hierarchical, palette, and multicolor — that give you multiple options when applying color to symbols. For example, you might want to use multiple opacities of your app’s accent color to give symbols depth and emphasis, or specify a palette of contrasting colors to display symbols that coordinate with various color schemes." }, { "type": "paragraph", "text": "To support the rendering modes, SF Symbols organizes a symbol’s paths into distinct layers. For example, the cloud.sun.rain.fill symbol consists of three layers: the primary layer contains the cloud paths, the secondary layer contains the paths that define the sun and its rays, and the tertiary layer contains the raindrop paths." }, { "type": "paragraph", "text": "Primary" }, { "type": "paragraph", "text": "Secondary" }, { "type": "paragraph", "text": "Tertiary" }, { "type": "paragraph", "text": "Depending on the rendering mode you choose, a symbol can produce various appearances. For example, Hierarchical rendering mode assigns a different opacity of a single color to each layer, creating a visual hierarchy that gives depth to the symbol." }, { "type": "paragraph", "text": "To learn more about supporting rendering modes in custom symbols, see Custom symbols." }, { "type": "paragraph", "text": "SF Symbols supports the following rendering modes." }, { "type": "paragraph", "text": "Monochrome — Applies one color to all layers in a symbol. Within a symbol, paths render in the color you specify or as a transparent shape within a color-filled path." }, { "type": "paragraph", "text": "Hierarchical — Applies one color to all layers in a symbol, varying the color’s opacity according to each layer’s hierarchical level." }, { "type": "paragraph", "text": "Palette — Applies two or more colors to a symbol, using one color per layer. Specifying only two colors for a symbol that defines three levels of hierarchy means the secondary and tertiary layers use the same color." }, { "type": "paragraph", "text": "Multicolor — Applies intrinsic colors to some symbols to enhance meaning. For example, the leaf symbol uses green to reflect the appearance of leaves in the physical world, whereas the trash.slash symbol uses red to signal data loss. Some multicolor symbols include layers that can receive other colors." }, { "type": "paragraph", "text": "Regardless of rendering mode, using system-provided colors ensures that symbols automatically adapt to accessibility accommodations and appearance modes like vibrancy and Dark Mode. For developer guidance, see renderingMode(_:)." }, { "type": "paragraph", "text": "Confirm that a symbol’s rendering mode works well in every context. Depending on factors like the size of a symbol and its contrast with the current background color, different rendering modes can affect how well people can discern the symbol’s details. You can use the automatic setting to get a symbol’s preferred rendering mode, but it’s still a good idea to check the results for places where a different rendering mode might improve a symbol’s legibility." } ] }, { "heading": "Gradients", "level": 2, "content": [ { "type": "paragraph", "text": "In SF Symbols 7 and later, gradient rendering generates a smooth linear gradient from a single source color. You can use gradients across all rendering modes for both system and custom colors and for custom symbols. Gradients render for symbols of any size, but look best at larger sizes." }, { "type": "paragraph", "text": "Solid fill" }, { "type": "paragraph", "text": "Gradient fill" } ] }, { "heading": "Variable color", "level": 2, "content": [ { "type": "paragraph", "text": "With variable color, you can represent a characteristic that can change over time — like capacity or strength — regardless of rendering mode. To visually communicate such a change, variable color applies color to different layers of a symbol as a value reaches different thresholds between zero and 100 percent." }, { "type": "paragraph", "text": "For example, you could use variable color with the speaker.wave.3 symbol to communicate three different ranges of sound — plus the state where there’s no sound — by mapping the layers that represent the curved wave paths to different ranges of decibel values. In the case of no sound, no wave layers get color. In all other cases, a wave layer receives color when the sound reaches a threshold the system defines based on the number of nonzero states you want to represent." }, { "type": "paragraph", "text": "Sometimes, it can make sense for some of a symbol’s layers to opt out of variable color. For example, in the speaker.wave.3 symbol shown above, the layer that contains the speaker path doesn’t receive variable color because a speaker doesn’t change as the sound level changes. A symbol can support variable color in any number of layers." }, { "type": "paragraph", "text": "Use variable color to communicate change — don’t use it to communicate depth. To convey depth and visual hierarchy, use Hierarchical rendering mode to elevate certain layers and distinguish foreground and background elements in a symbol." } ] }, { "heading": "Weights and scales", "level": 2, "content": [ { "type": "paragraph", "text": "SF Symbols provides symbols in a wide range of weights and scales to help you create adaptable designs." }, { "type": "paragraph", "text": "Each of the nine symbol weights — from ultralight to black — corresponds to a weight of the San Francisco system font, helping you achieve precise weight matching between symbols and adjacent text, while supporting flexibility for different sizes and contexts." }, { "type": "paragraph", "text": "Each symbol is also available in three scales: small, medium (the default), and large. The scales are defined relative to the cap height of the San Francisco system font." }, { "type": "paragraph", "text": "Small" }, { "type": "paragraph", "text": "Medium" }, { "type": "paragraph", "text": "Large" }, { "type": "paragraph", "text": "Specifying a scale lets you adjust a symbol’s emphasis compared to adjacent text, without disrupting the weight matching with text that uses the same point size. For developer guidance, see imageScale(_:) (SwiftUI), UIImage.SymbolScale (UIKit), and NSImage.SymbolConfiguration (AppKit)." } ] }, { "heading": "Design variants", "level": 2, "content": [ { "type": "paragraph", "text": "SF Symbols defines several design variants — such as fill, slash, and enclosed — that can help you communicate precise states and actions while maintaining visual consistency and simplicity in your UI. For example, you could use the slash variant of a symbol to show that an item or action is unavailable, or use the fill variant to indicate selection." }, { "type": "paragraph", "text": "Outline is the most common variant in SF Symbols. An outlined symbol has no solid areas, resembling the appearance of text. Most symbols are also available in a fill variant, in which the areas within some shapes are solid." }, { "type": "paragraph", "text": "In addition to outline and fill, SF Symbols also defines variants that include a slash or enclose a symbol within a shape like a circle, square, or rectangle. In many cases, enclosed and slash variants can combine with outline or fill variants." }, { "type": "paragraph", "text": "SF Symbols provides many variants for specific languages and writing systems, including Latin, Arabic, Hebrew, Hindi, Thai, Chinese, Japanese, Korean, Cyrillic, Devanagari, and several Indic numeral systems. Language- and script-specific variants adapt automatically when the device language changes. For guidance, see Images." }, { "type": "paragraph", "text": "Symbol variants support a range of design goals. For example:" }, { "type": "list", "items": [ "The outline variant works well in toolbars, lists, and other places where you display a symbol alongside text.", "Symbols that use an enclosing shape — like a square or circle — can improve legibility at small sizes.", "The solid areas in a fill variant tend to give a symbol more visual emphasis, making it a good choice for iOS tab bars and swipe actions and places where you use an accent color to communicate selection." ] }, { "type": "paragraph", "text": "In many cases, the view that displays a symbol determines whether to use outline or fill, so you don’t have to specify a variant. For example, an iOS tab bar prefers the fill variant, whereas a toolbar takes the outline variant." } ] }, { "heading": "Animations", "level": 2, "content": [ { "type": "paragraph", "text": "SF Symbols provides a collection of expressive, configurable animations that enhance your interface and add vitality to your app. Symbol animations help communicate ideas, provide feedback in response to people’s actions, and signal changes in status or ongoing activities." }, { "type": "paragraph", "text": "Animations work on all SF Symbols in the library, in all rendering modes, weights, and scales, and on custom symbols. For considerations when animating custom symbols, see Custom symbols. You can control the playback of an animation, whether you want the animation to run from start to finish, or run indefinitely, repeating its effect until a condition is met. You can customize behaviors, like changing the playback speed of an animation or determining whether to reverse an animation before repeating it. For developer guidance, see Symbols and SymbolEffect." }, { "type": "paragraph", "text": "Appear — Causes a symbol to gradually emerge into view." }, { "type": "paragraph", "text": "Disappear — Causes a symbol to gradually recede out of view." }, { "type": "paragraph", "text": "Bounce — Briefly scales a symbol with an elastic-like movement that goes either up or down and then returns to the symbol’s initial state. The bounce animation plays once by default and can help communicate that an action occurred or needs to take place." }, { "type": "paragraph", "text": "Scale — Changes the size of a symbol, increasing or decreasing its scale. Unlike the bounce animation, which returns the symbol to its original state, the scale animation persists until you set a new scale or remove the effect. You might use the scale animation to draw people’s attention to a selected item or as feedback when people choose a symbol." }, { "type": "paragraph", "text": "Pulse — Varies the opacity of a symbol over time. This animation automatically pulses only the layers within a symbol that are annotated to pulse, and optionally can pulse all layers within a symbol. You might use the pulse animation to communicate ongoing activity, playing it continuously until a condition is met." }, { "type": "paragraph", "text": "Variable color — Incrementally varies the opacity of layers within a symbol. This animation can be cumulative or iterative. When cumulative, color changes persist for each layer until the animation cycle is complete. When iterative, color changes occur one layer at a time. You might use variable color to communicate progress or ongoing activity, such as playback, connecting, or broadcasting. You can customize the animation to autoreverse — meaning reverse the animation to the starting point and replay the sequence — as well as hide inactive layers rather than reduce their opacity." }, { "type": "paragraph", "text": "The arrangement of layers within a symbol determines how variable color behaves during a repeating animation. Symbols with layers that are arranged linearly where the start and end points don’t meet are annotated as open loop. Symbols with layers that follow a complete shape where the start and end points do meet, like in a circular progress indicator, are annotated as closed loop. Variable color animations for symbols with closed loop designs feature seamless, continuous playback." }, { "type": "paragraph", "text": "Replace — Replaces one symbol with another. The replace animation works between arbitrary symbols and across all weights and rendering modes. This animation features three configurations:" }, { "type": "list", "items": [ "Down-up, where the outgoing symbol scales down and the incoming symbol scales up, communicating a change in state.", "Up-up, where both the outgoing and incoming symbols scale up. This configuration communicates a change in state that includes a sense of forward progression.", "Off-up, where the outgoing symbol hides immediately and the incoming symbol scales up. This configuration communicates a state change that emphasizes the next available state or action." ] }, { "type": "image", "alt": "", "caption": "From left to right: down-up, up-up, off-up" }, { "type": "paragraph", "text": "Magic Replace — Performs a smart transition between two symbols with related shapes. For example, slashes can draw on and off, and badges can appear or disappear, or you can replace them independently of the base symbol. Magic Replace is the new default replace animation, but doesn’t occur between unrelated symbols; the default down-up animation occurs instead. You can choose a custom direction for the fallback animation in these situations if you prefer one other than the default." }, { "type": "paragraph", "text": "Wiggle — Moves the symbol back and forth along a directional axis. You might use the wiggle animation to highlight a change or a call to action that a person might overlook. Wiggle can also add a dynamic emphasis to an interaction or reinforce what the symbol is representing, such as when an arrow points in a specific direction." }, { "type": "paragraph", "text": "Breathe — Smoothly increases and decreases the presence of a symbol, giving it a living quality. You might use the breathe animation to convey status changes, or signal that an activity is taking place, like an ongoing recording session. Breathe is similar to pulse; however pulse animates by changing opacity alone, while breathe changes both opacity and size to convey ongoing activity." }, { "type": "paragraph", "text": "Rotate — Rotates the symbol to act as a visual indicator or imitate an object’s behavior in the real world. For example, when a task is in progress, rotation confirms that it’s working as expected. The rotate animation causes some symbols to rotate entirely, while in others only certain parts of the symbol rotate. Symbols like the desk fan, for example, use the By Layer rotation option to spin only the fan blades." }, { "type": "paragraph", "text": "Draw On / Draw Off — In SF Symbols 7 and later, draws the symbol along a path through a set of guide points, either from offscreen to onscreen (Draw On) or from onscreen to offscreen (Draw Off). You can draw all layers at once, stagger them, or draw each layer one at a time. You might use the draw animation to convey progress, as with a download, or to reinforce the meaning of a symbol, like a directional arrow." }, { "type": "paragraph", "text": "Apply symbol animations judiciously. While there’s no limit to how many animations you can add to a view, too many animations can overwhelm an interface and distract people." }, { "type": "paragraph", "text": "Make sure that animations serve a clear purpose in communicating a symbol’s intent. Each type of animation has a discrete movement that communicates a certain type of action or elicits a certain response. Consider how people might interpret an animated symbol and whether the animation, or combination of animations, might be confusing." }, { "type": "paragraph", "text": "Use symbol animations to communicate information more efficiently. Animations provide visual feedback, reinforcing that something happened in your interface. You can use animations to present complex information in a simple way and without taking up a lot of visual space." }, { "type": "paragraph", "text": "Consider your app’s tone when adding animations. When animating a symbol, think about what the animation can convey and how that might align with your brand identity and your app’s overall style and tone. For guidance, see Branding." } ] }, { "heading": "Custom symbols", "level": 2, "content": [ { "type": "paragraph", "text": "If you need a symbol that SF Symbols doesn’t provide, you can create your own. To create a custom symbol, first export the template for a symbol that’s similar to the design you want, then use a vector-editing tool to modify it. For developer guidance, see Creating custom symbol images for your app." }, { "type": "important", "text": "ImportantSF Symbols includes copyrighted symbols that depict Apple products and features. You can display these symbols in your app, but you can’t customize them. To help you identify a noncustomizable symbol, the SF Symbols app badges it with an Info icon; to help you use the symbol correctly, the inspector pane describes its usage restrictions." }, { "type": "paragraph", "text": "Using a process called annotating, you can assign a specific color — or a specific hierarchical level, such as primary, secondary, or tertiary — to each layer in a custom symbol. Depending on the rendering modes you support, you can use a different mode in each instance of the symbol in your app." }, { "type": "paragraph", "text": "Use the template as a guide. Create a custom symbol that’s consistent with the ones the system provides in level of detail, optical weight, alignment, position, and perspective. Strive to design a symbol that is:" }, { "type": "list", "items": [ "Simple", "Recognizable", "Inclusive", "Directly related to the action or content it represents" ] }, { "type": "paragraph", "text": "For guidance, see Icons." }, { "type": "paragraph", "text": "Assign negative side margins to your custom symbol if necessary. SF Symbols supports negative side margins to aid optical horizontal alignment when a symbol contains a badge or other elements that increase its width. For example, negative side margins can help you horizontally align a stack of folder symbols, some of which include a badge. The name of each margin includes the relevant configuration — such as “left-margin-Regular-M” — so be sure to use this naming pattern if you add margins to your custom symbols." }, { "type": "paragraph", "text": "Optimize layers to use animations with custom symbols. If you want to animate your symbol by layer, make sure to annotate the layers in the SF Symbols app. The Z-order determines the order that you want to apply colors to the layers of a variable color symbol, and you can choose whether to animate those changes from front-to-back, or back-to-front. You can also animate by layer groups to have related layers move together." }, { "type": "paragraph", "text": "Test animations for custom symbols. It’s important to test your custom symbols with all of the animation presets because the shapes and paths might not appear how you expect when the layers are in motion. To get the most out of this feature, consider drawing your custom symbols with whole shapes. For example, a custom symbol similar to the person.2.fill symbol doesn’t need to create a cutout for the shape representing the person on the left. Instead, you can draw the full shape of the person, and in addition to that, draw an offset path of the person on the right to help represent the gap between them. You can later annotate this offset path as an erase layer to render the symbol as you want. This method of drawing helps preserve additional layer information that allows for animations to perform as you expect." }, { "type": "paragraph", "text": "Avoid making custom symbols that include common variants, such as enclosures or badges. The SF Symbols app offers a component library for creating variants of your custom symbol. Using the component library allows you to create commonly used variants of your custom symbol while maintaining design consistency with the included SF Symbols." }, { "type": "paragraph", "text": "Provide alternative text labels for custom symbols. Alternative text labels — or accessibility descriptions — let VoiceOver describe visible UI and content, making navigation easier for people with visual disabilities. For guidance, see VoiceOver." }, { "type": "paragraph", "text": "Don’t design replicas of Apple products. Apple products are copyrighted and you can’t reproduce them in your custom symbols. Also, you can’t customize a symbol that SF Symbols identifies as representing an Apple feature or product." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Download SF Symbols" }, { "type": "paragraph", "text": "Typography" }, { "type": "paragraph", "text": "Icons" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Symbols — Symbols framework" }, { "type": "paragraph", "text": "Configuring and displaying symbol images in your UI — UIKit" }, { "type": "paragraph", "text": "Creating custom symbol images for your app — UIKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "July 28, 2025", "Updated with guidance for Draw animations and gradient rendering in SF Symbols 7." ], [ "June 10, 2024", "Updated with guidance for new animations and features of SF Symbols 6." ], [ "June 5, 2023", "Added a new section on animations. Included animation guidance for custom symbols." ], [ "September 14, 2022", "Added a new section on variable color. Removed instructions on creating custom symbol paths, exporting templates, and layering paths, deferring to developer articles that cover these topics." ] ] } ] } ], "platforms": [], "related": [ { "title": "Rendering modes", "url": "/design/human-interface-guidelines/sf-symbols#Rendering-modes" }, { "title": "Custom symbols", "url": "/design/human-interface-guidelines/sf-symbols#Custom-symbols" }, { "title": "Gradients", "url": "/design/human-interface-guidelines/sf-symbols#Gradients" }, { "title": "Variable color", "url": "/design/human-interface-guidelines/sf-symbols#Variable-color" }, { "title": "Weights and scales", "url": "/design/human-interface-guidelines/sf-symbols#Weights-and-scales" }, { "title": "Design variants", "url": "/design/human-interface-guidelines/sf-symbols#Design-variants" }, { "title": "Images", "url": "/design/human-interface-guidelines/right-to-left#Images" }, { "title": "Animations", "url": "/design/human-interface-guidelines/sf-symbols#Animations" }, { "title": "Branding", "url": "/design/human-interface-guidelines/branding" }, { "title": "Icons", "url": "/design/human-interface-guidelines/icons" }, { "title": "VoiceOver", "url": "/design/human-interface-guidelines/voiceover" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/sf-symbols#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/sf-symbols#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/sf-symbols#Related" }, { "title": "Typography", "url": "/design/human-interface-guidelines/typography" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/sf-symbols#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/sf-symbols#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/sf-symbols#Change-log" } ], "image_count": 1 }, { "title": "Scroll views", "url": "https://developer.apple.com/design/human-interface-guidelines/scroll-views", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "The scroll view itself has no appearance, but it can display a translucent scroll indicator that typically appears after people begin scrolling the view’s content. Although the appearance and behavior of scroll indicators can vary per platform, all indicators provide visual feedback about the scrolling action. For example, in iOS, iPadOS, macOS, visionOS, and watchOS, the indicator shows whether the currently visible content is near the beginning, middle, or end of the view." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Support default scrolling gestures and keyboard shortcuts. People are accustomed to the systemwide scrolling behavior and expect it to work everywhere. If you build custom scrolling for a view, make sure your scroll indicators use the elastic behavior that people expect." }, { "type": "paragraph", "text": "Make it apparent when content is scrollable. Because scroll indicators aren’t always visible, it can be helpful to make it obvious when content extends beyond the view. For example, displaying partial content at the edge of a view indicates that there’s more content in that direction. Although most people immediately try scrolling a view to discover if additional content is available, it’s considerate to draw their attention to it." }, { "type": "paragraph", "text": "Avoid putting a scroll view inside another scroll view with the same orientation. Nesting scroll views that have the same orientation can create an unpredictable interface that’s difficult to control. It’s alright to place a horizontal scroll view inside a vertical scroll view (or vice versa), however." }, { "type": "paragraph", "text": "Consider supporting page-by-page scrolling if it makes sense for your content. In some situations, people appreciate scrolling by a fixed amount of content per interaction instead of scrolling continuously. On most platforms, you can define the size of such a page — typically the current height or width of the view — and define an interaction that scrolls one page at a time. To help maintain context during page-by-page scrolling, you can define a unit of overlap, such as a line of text, a row of glyphs, or part of a picture, and subtract the unit from the page size. For developer guidance, see PagingScrollTargetBehavior." }, { "type": "paragraph", "text": "In some cases, scroll automatically to help people find their place. Although people initiate almost all scrolling, automatic scrolling can be helpful when relevant content is no longer in view, such as when:" }, { "type": "list", "items": [ "Your app performs an operation that selects content or places the insertion point in an area that’s currently hidden. For example, when your app locates text that people are searching for, scroll the content to bring the new selection into view.", "People start entering information in a location that’s not currently visible. For example, if the insertion point is on one page and people navigate to another page, scroll back to the insertion point as soon as they begin to enter text.", "The pointer moves past the edge of the view while people are making a selection. In this case, follow the pointer by scrolling in the direction it moves.", "People select something and scroll to a new location before acting on the selection. In this case, scroll until the selection is in view before performing the operation." ] }, { "type": "paragraph", "text": "In all cases, automatically scroll the content only as much as necessary to help people retain context. For example, if part of a selection is visible, you don’t need to scroll the entire selection into view." }, { "type": "paragraph", "text": "If you support zoom, set appropriate maximum and minimum scale values. For example, zooming in on text until a single character fills the screen doesn’t make sense in most situations." } ] }, { "heading": "Scroll edge effects", "level": 2, "content": [ { "type": "paragraph", "text": "In iOS, iPadOS, and macOS, a scroll edge effect is a variable blur that provides a transition between a content area and an area with Liquid Glass controls, such as toolbars. In most cases, the system applies a scroll edge effect automatically when a pinned element overlaps with scrolling content. If you use custom controls or layouts, the effect might not appear, and you may need to add it manually. For developer guidance, see ScrollEdgeEffectStyle and UIScrollEdgeEffect." }, { "type": "paragraph", "text": "There are two styles of scroll edge effect: soft and hard." }, { "type": "list", "items": [ "Use a soft edge effect in most cases, especially in iOS and iPadOS, to provide a subtle transition that works well for toolbars and interactive elements like buttons.", "Use a hard edge effect primarily in macOS for a stronger, more opaque boundary that’s ideal for interactive text, backless controls, or pinned table headers that need extra clarity." ] }, { "type": "paragraph", "text": "Only use a scroll edge effect when a scroll view is adjacent to floating interface elements. Scroll edge effects aren’t decorative. They don’t block or darken like overlays; they exist to clarify where controls and content meet." }, { "type": "paragraph", "text": "Apply one scroll edge effect per view. In split view layouts on iPad and Mac, each pane can have its own scroll edge effect; in this case, keep them consistent in height to maintain alignment." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "Consider showing a page control when a scroll view is in page-by-page mode. Page controls show how many pages, screens, or other chunks of content are available and indicates which one is currently visible. For example, Weather uses a page control to indicate movement between people’s saved locations. If you show a page control with a scroll view, don’t show the scrolling indicator on the same axis to avoid confusing people with redundant controls." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "In macOS, a scroll indicator is commonly called a scroll bar." }, { "type": "paragraph", "text": "If necessary, use small or mini scroll bars in a panel. When space is tight, you can use smaller scroll bars in panels that need to coexist with other windows. Be sure to use the same size for all controls in such a panel." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "Views in tvOS can scroll, but they aren’t treated as distinct objects with scroll indicators. Instead, when content exceeds the size of the screen, the system automatically scrolls the interface to keep focused items visible." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In visionOS, the scroll indicator has a small, fixed size to help communicate that people can scroll efficiently without making large movements. To make it easy to find, the scroll indicator always appears in a predictable location with respect to the window: vertically centered at the trailing edge during vertical scrolling and horizontally centered at the window’s bottom edge during horizontal scrolling." }, { "type": "paragraph", "text": "When people begin swiping content in the direction they want it to scroll, the scroll indicator appears at the window’s edge, visually reinforcing the effect of their gesture and providing feedback about the content’s current position and overall length. When people look at the scroll indicator and begin a drag gesture, the indicator enables a jog bar experience that lets people manipulate the scrolling speed instead of the content’s position. In this experience, the scroll indicator reveals tick marks that speed up or slow down as people make small adjustments to their gesture, providing visual feedback that helps people precisely control scrolling acceleration." }, { "type": "paragraph", "text": "If necessary, account for the size of the scroll indicator. Although the indicator’s overall size is small, it’s a little thicker than the same component in iOS. If your content uses tight margins, consider increasing them to prevent the scroll indicator from overlapping the content." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Prefer vertically scrolling content. People are accustomed to using the Digital Crown to navigate to and within apps on Apple Watch. If your app contains a single list or content view, rotating the Digital Crown scrolls vertically when your app’s content is taller than the height of the display." }, { "type": "paragraph", "text": "Use tab views to provide page-by-page scrolling. watchOS displays tab views as pages. If you place tab views in a vertical stack, people can rotate the Digital Crown to move vertically through full-screen pages of content. In this scenario, the system displays a page indicator next to the Digital Crown that shows people where they are in the content, both within the current page and within a set of pages. For guidance, see Tab views." }, { "type": "paragraph", "text": "When displaying paged content, consider limiting the content of an individual page to a single screen height. Embracing this constraint clarifies the purpose of each page, helping you create a more glanceable design. However, if your app has long pages, people can still use the Digital Crown both to navigate between shorter pages and to scroll content in a longer page because the page indicator expands into a scroll indicator when necessary. Use variable-height pages judiciously and place them after fixed-height pages when possible." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Page controls" }, { "type": "paragraph", "text": "Gestures" }, { "type": "paragraph", "text": "Pointing devices" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "ScrollView" }, { "type": "paragraph", "text": "UIScrollView" }, { "type": "paragraph", "text": "NSScrollView" }, { "type": "paragraph", "text": "WKPageOrientation" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "July 28, 2025", "Added guidance for scroll edge effects." ], [ "February 2, 2024", "Added artwork showing the behavior of the visionOS scroll indicator." ], [ "December 5, 2023", "Described the visionOS scroll indicator and added guidance for integrating it with window layout." ], [ "June 5, 2023", "Updated guidance for using scroll views in watchOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/scroll-views#Best-practices" }, { "title": "Scroll edge effects", "url": "/design/human-interface-guidelines/scroll-views#Scroll-edge-effects" }, { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "toolbars", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/scroll-views#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/scroll-views#iOS-iPadOS" }, { "title": "Page controls", "url": "/design/human-interface-guidelines/page-controls" }, { "title": "macOS", "url": "/design/human-interface-guidelines/scroll-views#macOS" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/scroll-views#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/scroll-views#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/scroll-views#watchOS" }, { "title": "Tab views", "url": "/design/human-interface-guidelines/tab-views" }, { "title": "Resources", "url": "/design/human-interface-guidelines/scroll-views#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/scroll-views#Related" }, { "title": "Gestures", "url": "/design/human-interface-guidelines/gestures" }, { "title": "Pointing devices", "url": "/design/human-interface-guidelines/pointing-devices" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/scroll-views#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/scroll-views#Change-log" } ], "image_count": 0 }, { "title": "Sidebars", "url": "https://developer.apple.com/design/human-interface-guidelines/sidebars", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "A sidebar floats above content without being anchored to the edges of the view. It provides a broad, flat view of an app’s information hierarchy, giving people access to several peer content areas or modes at the same time." }, { "type": "paragraph", "text": "A sidebar requires a large amount of vertical and horizontal space. When space is limited or you want to devote more of the screen to other information or functionality, a more compact control such as a tab bar may provide a better navigation experience. For guidance, see Layout." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Extend content beneath the sidebar. In iOS, iPadOS, and macOS, as with other controls such as toolbars and tab bars, sidebars float above content in the Liquid Glass layer. To reinforce the separation and floating appearance of the sidebar, extend content beneath it either by letting it horizontally scroll or applying a background extension view, which mirrors adjacent content to give the impression of stretching it under the sidebar. For developer guidance, see backgroundExtensionEffect()." }, { "type": "paragraph", "text": "When possible, let people customize the contents of a sidebar. A sidebar lets people navigate to important areas in your app, so it works well when people can decide which areas are most important and in what order they appear." }, { "type": "paragraph", "text": "Group hierarchy with disclosure controls if your app has a lot of content. Using disclosure controls helps keep the sidebar’s vertical space to a manageable level." }, { "type": "paragraph", "text": "Consider using familiar symbols to represent items in the sidebar. SF Symbols provides a wide range of customizable symbols you can use to represent items in your app. If you need to use a custom icon, consider creating a custom symbol rather than using a bitmap image. Download the SF Symbols app from Apple Design Resources." }, { "type": "paragraph", "text": "Consider letting people hide the sidebar. People sometimes want to hide the sidebar to create more room for content details or to reduce distraction. When possible, let people hide and show the sidebar using the platform-specific interactions they already know. For example, in iPadOS, people expect to use the built-in edge swipe gesture; in macOS, you can include a show/hide button or add Show Sidebar and Hide Sidebar commands to your app’s View menu. In visionOS, a window typically expands to accommodate a sidebar, so people rarely need to hide it. Avoid hiding the sidebar by default to ensure that it remains discoverable." }, { "type": "paragraph", "text": "In general, show no more than two levels of hierarchy in a sidebar. When a data hierarchy is deeper than two levels, consider using a split view interface that includes a content list between the sidebar items and detail view." }, { "type": "paragraph", "text": "If you need to include two levels of hierarchy in a sidebar, use succinct, descriptive labels to title each group. To help keep labels short, omit unnecessary words." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for tvOS. Not supported in watchOS." } ] }, { "heading": "iOS", "level": 3, "content": [ { "type": "paragraph", "text": "Avoid using a sidebar. A sidebar takes up a lot of space in landscape orientation and isn’t available in portrait orientation. Instead, consider using a tab bar, which takes less space and remains visible in both orientations." } ] }, { "heading": "iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "When you use the sidebarAdaptable style of tab view to present a sidebar, you choose whether to display a sidebar or a tab bar when your app opens. Both variations include a button that people can use to switch between them. This style also responds automatically to rotation and window resizing, providing a version of the control that’s appropriate to the width of the view." }, { "type": "note", "text": "Developer noteTo display a sidebar only, use NavigationSplitView to present a sidebar in the primary pane of a split view, or use UISplitViewController." }, { "type": "paragraph", "text": "Consider using a tab bar first. A tab bar provides more space to feature content, and offers enough flexibility to navigate between many apps’ main areas. If you need to expose more areas than fit in a tab bar, the tab bar’s convertible sidebar-style appearance can provide access to content that people use less frequently. For guidance, see Tab bars." }, { "type": "paragraph", "text": "If necessary, apply the correct appearance to a sidebar. If you’re not using SwiftUI to create a sidebar, you can use the UICollectionLayoutListConfiguration.Appearance.sidebar appearance of a collection view list layout. For developer guidance, see UICollectionLayoutListConfiguration.Appearance." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "A sidebar’s row height, text, and glyph size depend on its overall size, which can be small, medium, or large. You can set the size programmatically, but people can also change it by selecting a different sidebar icon size in General settings." }, { "type": "paragraph", "text": "Avoid stylizing your app by specifying a fixed color for all sidebar icons. By default, sidebar icons use the current accent color and people expect to see their chosen accent color throughout all the apps they use. Although a fixed color can help clarify the meaning of an icon, you want to make sure that most sidebar icons display the color people choose." }, { "type": "paragraph", "text": "Consider automatically hiding and revealing a sidebar when its container window resizes. For example, reducing the size of a Mail viewer window can automatically collapse its sidebar, making more room for message content." }, { "type": "paragraph", "text": "Avoid putting critical information or actions at the bottom of a sidebar. People often relocate a window in a way that hides its bottom edge." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "If your app’s hierarchy is deep, consider using a sidebar within a tab in a tab bar. In this situation, a sidebar can support secondary navigation within the tab. If you do this, be sure to prevent selections in the sidebar from changing which tab is currently open." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Split views" }, { "type": "paragraph", "text": "Tab bars" }, { "type": "paragraph", "text": "Layout" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "sidebarAdaptable — SwiftUI" }, { "type": "paragraph", "text": "NavigationSplitView — SwiftUI" }, { "type": "paragraph", "text": "sidebar — SwiftUI" }, { "type": "paragraph", "text": "UICollectionLayoutListConfiguration — UIKit" }, { "type": "paragraph", "text": "NSSplitViewController — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added guidance for extending content beneath the sidebar." ], [ "August 6, 2024", "Updated guidance to include the SwiftUI adaptable sidebar style." ], [ "December 5, 2023", "Added artwork for iPadOS." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "tab bar", "url": "/design/human-interface-guidelines/tab-bars" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/sidebars#Best-practices" }, { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "disclosure controls", "url": "/design/human-interface-guidelines/disclosure-controls" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "custom symbol", "url": "/design/human-interface-guidelines/sf-symbols#Custom-symbols" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/sidebars#Platform-considerations" }, { "title": "iOS", "url": "/design/human-interface-guidelines/sidebars#iOS" }, { "title": "iPadOS", "url": "/design/human-interface-guidelines/sidebars#iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/sidebars#macOS" }, { "title": "accent color", "url": "https://developer.apple.com/design/human-interface-guidelines/color#App-accent-colors" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/sidebars#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/sidebars#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/sidebars#Related" }, { "title": "Split views", "url": "/design/human-interface-guidelines/split-views" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/sidebars#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/sidebars#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/sidebars#Change-log" } ], "image_count": 0 }, { "title": "Sliders", "url": "https://developer.apple.com/design/human-interface-guidelines/sliders", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "As a slider’s value changes, the portion of track between the minimum value and the thumb fills with color. A slider can optionally display left and right icons that illustrate the meaning of the minimum and maximum values." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Customize a slider’s appearance if it adds value. You can adjust a slider’s appearance — including track color, thumb image and tint color, and left and right icons — to blend with your app’s design and communicate intent. A slider that adjusts image size, for example, could show a small image icon on the left and a large image icon on the right." }, { "type": "paragraph", "text": "Use familiar slider directions. People expect the minimum and maximum sides of sliders to be consistent in all apps, with minimum values on the leading side and maximum values on the trailing side (for horizontal sliders) and minimum values at the bottom and maximum values at the top (for vertical sliders). For example, people expect to be able to move a horizontal slider that represents a percentage from 0 percent on the leading side to 100 percent on the trailing side." }, { "type": "paragraph", "text": "Consider supplementing a slider with a corresponding text field and stepper. Especially when a slider represents a wide range of values, people may appreciate seeing the exact slider value and having the ability to enter a specific value in a text field. Adding a stepper provides a convenient way for people to increment in whole values. For related guidance, see Text fields and Steppers." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "Not supported in tvOS." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "Don’t use a slider to adjust audio volume. If you need to provide volume control in your app, use a volume view, which is customizable and includes a volume-level slider and a control for changing the active audio output device. For guidance, see Playing audio." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "Sliders in macOS can also include tick marks, making it easier for people to pinpoint a specific value within the range." }, { "type": "paragraph", "text": "In a linear slider either with or without tick marks, the thumb is a narrow lozenge shape, and the portion of track between the minimum value and the thumb is filled with color. A linear slider often includes supplementary icons that illustrate the meaning of the minimum and maximum values." }, { "type": "paragraph", "text": "In a circular slider, the thumb appears as a small circle. Tick marks, when present, appear as evenly spaced dots around the circumference of the slider." }, { "type": "paragraph", "text": "Linear slider without tick marks" }, { "type": "paragraph", "text": "Linear slider with tick marks" }, { "type": "paragraph", "text": "Circular slider" }, { "type": "paragraph", "text": "Consider giving live feedback as the value of a slider changes. Live feedback shows people results in real time. For example, your Dock icons are dynamically scaled when adjusting the Size slider in Dock settings." }, { "type": "paragraph", "text": "Choose a slider style that matches peoples’ expectations. A horizontal slider is ideal when moving between a fixed starting and ending point. For example, a graphics app might offer a horizontal slider for setting the opacity level of an object between 0 and 100 percent. Use circular sliders when values repeat or continue indefinitely. For example, a graphics app might use a circular slider to adjust the rotation of an object between 0 and 360 degrees. An animation app might use a circular slider to adjust how many times an object spins when animated — four complete rotations equals four spins, or 1440 degrees of rotation." }, { "type": "paragraph", "text": "Consider using a label to introduce a slider. Labels generally use sentence-style capitalization and end with a colon. For guidance, see Labels." }, { "type": "paragraph", "text": "Use tick marks to increase clarity and accuracy. Tick marks help people understand the scale of measurements and make it easier to locate specific values." }, { "type": "paragraph", "text": "Consider adding labels to tick marks for even greater clarity. Labels can be numbers or words, depending on the slider’s values. It’s unnecessary to label every tick mark unless doing so is needed to reduce confusion. In many cases, labeling only the minimum and maximum values is sufficient. When the values of the slider are nonlinear, like in the Energy Saver settings pane, periodic labels provide context. It’s also a good idea to provide a tooltip that displays the value of the thumb when people hold their pointer over it." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "Prefer horizontal sliders. It’s generally easier for people to gesture from side to side than up and down." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "A slider is a horizontal track — appearing as a set of discrete steps or as a continuous bar — that represents a finite range of values. People can tap buttons on the sides of the slider to increase or decrease its value by a predefined amount." }, { "type": "paragraph", "text": "Discrete" }, { "type": "paragraph", "text": "Continuous" }, { "type": "paragraph", "text": "If necessary, create custom glyphs to communicate what the slider does. The system displays plus and minus signs by default." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Steppers" }, { "type": "paragraph", "text": "Pickers" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Slider — SwiftUI" }, { "type": "paragraph", "text": "UISlider — UIKit" }, { "type": "paragraph", "text": "NSSlider — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/sliders#Best-practices" }, { "title": "Text fields", "url": "/design/human-interface-guidelines/text-fields" }, { "title": "Steppers", "url": "/design/human-interface-guidelines/steppers" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/sliders#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/sliders#iOS-iPadOS" }, { "title": "Playing audio", "url": "/design/human-interface-guidelines/playing-audio" }, { "title": "macOS", "url": "/design/human-interface-guidelines/sliders#macOS" }, { "title": "Labels", "url": "/design/human-interface-guidelines/labels" }, { "title": "tooltip", "url": "https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/sliders#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/sliders#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/sliders#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/sliders#Related" }, { "title": "Pickers", "url": "/design/human-interface-guidelines/pickers" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/sliders#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/sliders#Change-log" } ], "image_count": 0 }, { "title": "Spatial layout", "url": "https://developer.apple.com/design/human-interface-guidelines/spatial-layout", "category": "foundations", "summary": "", "sections": [ { "heading": "Field of view", "level": 2, "content": [ { "type": "paragraph", "text": "A person’s field of view is the space they can see without moving their head. The dimensions of an individual’s field of view while wearing Apple Vision Pro vary based on factors like the way people configure the Light Seal and the extent of their peripheral acuity." }, { "type": "important", "text": "ImportantThe system doesn’t provide information about a person’s field of view." }, { "type": "paragraph", "text": "Center important content within the field of view. By default, visionOS launches an app directly in front of people, placing it within their field of view. In an immersive experience, you can help people keep their attention on important content by keeping it centered and not displaying distracting motion or bright, high-contrast objects in the periphery." }, { "type": "paragraph", "text": "Avoid anchoring content to the wearer’s head. Although you generally want your app to stay within the field of view, anchoring content so that it remains statically in front of someone can make them feel stuck, confined, and uncomfortable, especially if the content obscures a lot of passthrough and decreases the apparent stability of their surroundings. Instead, anchor content in people’s space, giving them the freedom to look around naturally and view different objects in different locations." } ] }, { "heading": "Depth", "level": 2, "content": [ { "type": "paragraph", "text": "People rely on visual cues like distance, occlusion, and shadow to perceive depth and make sense of their surroundings. On Apple Vision Pro, the system automatically uses visual effects like color temperature, reflections, and shadow to help people perceive the depth of virtual content. When people move a virtual object in space — or when they change their position relative to that object — the visual effects change the object’s apparent depth, making the experience feel more lifelike." }, { "type": "paragraph", "text": "Because people can view your content from any angle, incorporating small amounts of depth throughout your interface — even in standard windows — can help it look more natural. When you use SwiftUI, the system adds visual effects to views in a 2D window, making them appear to have depth. For developer guidance, see Adding 3D content to your app." }, { "type": "paragraph", "text": "If you need to present content with additional depth, you use RealityKit to create a 3D object (for developer guidance, see RealityKit). You can display the 3D object anywhere, or you can use a volume, which is a component that displays 3D content. A volume is similar to a window, but without a visible frame. For guidance, see visionOS volumes." }, { "type": "paragraph", "text": "Provide visual cues that accurately communicate the depth of your content. If visual cues are missing or they conflict with a person’s real-world experience, people can experience visual discomfort." }, { "type": "paragraph", "text": "Use depth to communicate hierarchy. Depth helps an object appear to stand out from surrounding content, making it more noticeable. People also tend to notice changes in depth: for example, when a sheet appears over a window, the window recedes along the z-axis, allowing the sheet to come forward and become visually prominent." }, { "type": "paragraph", "text": "In general, avoid adding depth to text. Text that appears to hover above its background is difficult to read, which slows people down and can sometimes cause vision discomfort." }, { "type": "paragraph", "text": "Make sure depth adds value. In general, you want to use depth to clarify and delight — you don’t need to use it everywhere. As you add depth to your design, think about the size and relative importance of objects. Depth is great for visually separating large, important elements in your app, like making a tab bar or toolbar stand out from a window, but it may not work as well on small objects. For example, using depth to make a button’s symbol stand out from its background can make the button less legible and harder to use. Also review how often you use different depths throughout your app. People need to refocus their eyes to perceive each difference in depth, and doing so too often or quickly can be tiring." } ] }, { "heading": "Scale", "level": 2, "content": [ { "type": "paragraph", "text": "visionOS defines two types of scale to preserve the appearance of depth while optimizing usability." }, { "type": "paragraph", "text": "Dynamic scale helps content remain comfortably legible and interactive regardless of its proximity to people. Specifically, visionOS automatically increases a window’s scale as it moves away from the wearer and decreases it as the window moves closer, making the window appear to maintain the same size at all distances." }, { "type": "paragraph", "text": "Fixed scale means that an object maintains the same scale regardless of its proximity to people. A fixed-scale object appears smaller when it moves farther from the viewer along the z-axis, similar to the way an object in a person’s physical surroundings looks smaller when it’s far away than it does when it’s close up." }, { "type": "paragraph", "text": "To support dynamic scaling and the appearance of depth, visionOS defines a point as an angle, in contrast to other platforms, which define a point as a number of pixels that can vary with the resolution of a 2D display." }, { "type": "paragraph", "text": "Consider using fixed scale when you want a virtual object to look exactly like a physical object. For example, you might want to maintain the life-size scale of a product you offer so it can look more realistic when people view it in their space. Because interactive content needs to scale to maintain usability as it gets closer or farther away, prefer applying fixed scale sparingly, reserving it for noninteractive objects that need it." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Avoid displaying too many windows. Too many windows can obscure people’s surroundings, making them feel overwhelmed, constricted, and even uncomfortable. It can also make it cumbersome for people to relocate an app because it means moving a lot of windows." }, { "type": "paragraph", "text": "Prioritize standard, indirect gestures. People can make an indirect gesture without moving their hand into their field of view. In contrast, making a direct gesture requires people to touch the virtual object with their finger, which can be tiring, especially when the object is positioned at or above their line of sight. In visionOS, people use indirect gestures to perform the standard gestures they already know. When you prioritize indirect gestures, people can use them to interact with any object they look at, whatever its distance. If you support direct gestures, consider reserving them for nearby objects that invite close inspection or manipulation for short periods of time. For guidance, see Gestures > visionOS." }, { "type": "paragraph", "text": "Rely on the Digital Crown to help people recenter windows in their field of view. When people move or turn their head, content might no longer appear where they want it to. If this happens, people can press the Digital Crown when they want to recenter content in front of them. Your app doesn’t need to do anything to support this action." }, { "type": "paragraph", "text": "Include enough space around interactive components to make them easy for people to look at. When people look at an interactive element, visionOS displays a visual hover effect that helps them confirm the element is the one they want. It’s crucial to include enough space around an interactive component so that looking at it is easy and comfortable, while preventing the hover effect from crowding other content. For example, place multiple, regular-size buttons so their centers are at least 60 points apart, leaving 16 points or more of space between them. Also, don’t let controls overlap other interactive elements or views, because doing so can make selecting a single element difficult." }, { "type": "paragraph", "text": "Let people use your app with minimal or no physical movement. Unless some physical movement is essential to your experience, help everyone enjoy it while remaining stationary." }, { "type": "paragraph", "text": "Use the floor to help you place a large immersive experience. If your immersive experience includes content that extends up from the floor, place it using a flat horizontal plane. Aligning this plane with the floor can help it blend seamlessly with people’s surroundings and provide a more intuitive experience." }, { "type": "paragraph", "text": "To learn more about windows and volumes in visionOS, see Windows > visionOS; for guidance on laying content within a window, see Layout > visionOS." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "Not supported in iOS, iPadOS, macOS, tvOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Eyes" }, { "type": "paragraph", "text": "Layout" }, { "type": "paragraph", "text": "Immersive experiences" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Presenting windows and spaces — visionOS" }, { "type": "paragraph", "text": "Positioning and sizing windows — visionOS" }, { "type": "paragraph", "text": "Adding 3D content to your app — visionOS" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "March 29, 2024", "Emphasized the importance of keeping interactive elements from overlapping each other." ], [ "June 21, 2023", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Field of view", "url": "/design/human-interface-guidelines/spatial-layout#Field-of-view" }, { "title": "Depth", "url": "/design/human-interface-guidelines/spatial-layout#Depth" }, { "title": "visionOS volumes", "url": "/design/human-interface-guidelines/windows#visionOS-volumes" }, { "title": "Scale", "url": "/design/human-interface-guidelines/spatial-layout#Scale" }, { "title": "resolution", "url": "/design/human-interface-guidelines/images#Resolution" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/spatial-layout#Best-practices" }, { "title": "Gestures > visionOS", "url": "/design/human-interface-guidelines/gestures#visionOS" }, { "title": "Digital Crown", "url": "/design/human-interface-guidelines/digital-crown" }, { "title": "buttons", "url": "/design/human-interface-guidelines/buttons#visionOS" }, { "title": "Windows > visionOS", "url": "/design/human-interface-guidelines/windows#visionOS" }, { "title": "Layout > visionOS", "url": "/design/human-interface-guidelines/layout#visionOS" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/spatial-layout#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/spatial-layout#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/spatial-layout#Related" }, { "title": "Eyes", "url": "/design/human-interface-guidelines/eyes" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Immersive experiences", "url": "/design/human-interface-guidelines/immersive-experiences" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/spatial-layout#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/spatial-layout#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/spatial-layout#Change-log" } ], "image_count": 0 }, { "title": "Split views", "url": "https://developer.apple.com/design/human-interface-guidelines/split-views", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Typically, you use a split view to show multiple levels of your app’s hierarchy at once and support navigation between them. In this scenario, selecting an item in the view’s primary pane displays the item’s contents in the secondary pane. Similarly, a split view can display a tertiary pane if items in the secondary pane contain additional content." }, { "type": "paragraph", "text": "It’s common to use a split view to display a sidebar for navigation, where the leading pane lists the top-level items or collections in an app, and the secondary and optional tertiary panes can present child collections and item details. Rarely, you might also use a split view to provide groups of functionality that supplement the primary view — for example, Keynote in macOS uses split view panes to present the slide navigator, the presenter notes, and the inspector pane in areas that surround the main slide canvas." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "To support navigation, persistently highlight the current selection in each pane that leads to the detail view. The selected appearance clarifies the relationship between the content in various panes and helps people stay oriented." }, { "type": "paragraph", "text": "Consider letting people drag and drop content between panes. Because a split view provides access to multiple levels of hierarchy, people can conveniently move content from one part of your app to another by dragging items to different panes. For guidance, see Drag and drop." } ] }, { "heading": "iOS", "level": 3, "content": [ { "type": "paragraph", "text": "Prefer using a split view in a regular — not a compact — environment. A split view needs horizontal space in which to display multiple panes. In a compact environment, such as iPhone in portrait orientation, it’s difficult to display multiple panes without wrapping or truncating the content, making it less legible and harder to interact with." } ] }, { "heading": "iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "In iPadOS, a split view can include either two vertical panes, like Mail, or three vertical panes, like Keynote." }, { "type": "paragraph", "text": "Account for narrow, compact, and intermediate window widths. Since iPad windows are fluidly resizable, it’s important to consider the design of a split view layout at multiple widths. In particular, ensure that it’s possible to navigate between the various panes in a logical way. For guidance, see Layout. For developer guidance, see NavigationSplitView and UISplitViewController." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "In macOS, you can arrange the panes of a split view vertically, horizontally, or both. A split view includes dividers between panes that can support dragging to resize them. For developer guidance, see VSplitView and HSplitView." }, { "type": "paragraph", "text": "Set reasonable defaults for minimum and maximum pane sizes. If people can resize the panes in your app’s split view, make sure to use sizes that keep the divider visible. If a pane gets too small, the divider can seem to disappear, becoming difficult to use." }, { "type": "paragraph", "text": "Consider letting people hide a pane when it makes sense. If your app includes an editing area, for example, consider letting people hide other panes to reduce distractions or allow more room for editing — in Keynote, people can hide the navigator and presenter notes panes when they want to edit slide content." }, { "type": "paragraph", "text": "Provide multiple ways to reveal hidden panes. For example, you might provide a toolbar button or a menu command — including a keyboard shortcut — that people can use to restore a hidden pane." }, { "type": "paragraph", "text": "Prefer the thin divider style. The thin divider measures one point in width, giving you maximum space for content while remaining easy for people to use. Avoid using thicker divider styles unless you have a specific need. For example, if both sides of a divider present table rows that use strong linear elements that might make a thin divider hard to distinguish, it might work to use a thicker divider. For developer guidance, see NSSplitView.DividerStyle." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "In tvOS, a split view can work well to help people filter content. When people choose a filter category in the primary pane, your app can display the results in the secondary pane." }, { "type": "paragraph", "text": "Choose a split view layout that keeps the panes looking balanced. By default, a split view devotes a third of the screen width to the primary pane and two-thirds to the secondary pane, but you can also specify a half-and-half layout." }, { "type": "paragraph", "text": "Display a single title above a split view, helping people understand the content as a whole. People already know how to use a split view to navigate and filter content; they don’t need titles that describe what each pane contains." }, { "type": "paragraph", "text": "Choose the title’s alignment based on the type of content the secondary pane contains. Specifically, when the secondary pane contains a content collection, consider centering the title in the window. In contrast, if the secondary pane contains a single main view of important content, consider placing the title above the primary view to give the content more room." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "To display supplementary information, prefer a split view instead of a new window. A split view gives people convenient access to more information without leaving the current context, whereas a new window may confuse people who are trying to navigate or reposition content. Opening more windows also requires you to carefully manage the relationship between views in your app or game. If you need to request a small amount of information or present a simple task that someone must complete before returning to their main task, use a sheet." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "In watchOS, the split view displays either the list view or a detail view as a full-screen view." }, { "type": "paragraph", "text": "Automatically display the most relevant detail view. When your app launches, show people the most pertinent information. For example, display information relevant to their location, the time, or their recent actions." }, { "type": "paragraph", "text": "If your app displays multiple detail pages, place the detail views in a vertical tab view. People can then use the Digital Crown to scroll between the detail view’s tabs. watchOS also displays a page indicator next to the Digital Crown, indicating the number of tabs and the currently selected tab." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Sidebars" }, { "type": "paragraph", "text": "Tab bars" }, { "type": "paragraph", "text": "Layout" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "NavigationSplitView — SwiftUI" }, { "type": "paragraph", "text": "UISplitViewController — UIKit" }, { "type": "paragraph", "text": "NSSplitViewController — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added iOS and iPadOS platform considerations." ], [ "December 5, 2023", "Added guidance for split views in visionOS." ], [ "June 5, 2023", "Added guidance for split views in watchOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "sidebar", "url": "/design/human-interface-guidelines/sidebars" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/split-views#Best-practices" }, { "title": "Drag and drop", "url": "/design/human-interface-guidelines/drag-and-drop" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/split-views#Platform-considerations" }, { "title": "iOS", "url": "/design/human-interface-guidelines/split-views#iOS" }, { "title": "iPadOS", "url": "/design/human-interface-guidelines/split-views#iPadOS" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "macOS", "url": "/design/human-interface-guidelines/split-views#macOS" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/split-views#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/split-views#visionOS" }, { "title": "sheet", "url": "/design/human-interface-guidelines/sheets" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/split-views#watchOS" }, { "title": "tab view", "url": "/design/human-interface-guidelines/tab-views" }, { "title": "Resources", "url": "/design/human-interface-guidelines/split-views#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/split-views#Related" }, { "title": "Tab bars", "url": "/design/human-interface-guidelines/tab-bars" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/split-views#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/split-views#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/split-views#Change-log" } ], "image_count": 0 }, { "title": "Tab bars", "url": "https://developer.apple.com/design/human-interface-guidelines/tab-bars", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Tab bars help people understand the different types of information or functionality that an app provides. They also let people quickly switch between sections of the view while preserving the current navigation state within each section." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Use a tab bar to support navigation, not to provide actions. A tab bar lets people navigate among different sections of an app, like the Alarm, Stopwatch, and Timer tabs in the Clock app. If you need to provide controls that act on elements in the current view, use a toolbar instead." }, { "type": "paragraph", "text": "Make sure the tab bar is visible when people navigate to different sections of your app. If you hide the tab bar, people can forget which area of the app they’re in. The exception is when a modal view covers the tab bar, because a modal is temporary and self-contained." }, { "type": "paragraph", "text": "Use the appropriate number of tabs required to help people navigate your app. As a representation of your app’s hierarchy, it’s important to weigh the complexity of additional tabs against the need for people to frequently access each section; keep in mind that it’s generally easier to navigate among fewer tabs. Where available, consider a sidebar or a tab bar that adapts to a sidebar as an alternative for an app with a complex information structure." }, { "type": "paragraph", "text": "Avoid overflow tabs. Depending on device size and orientation, the number of visible tabs can be smaller than the total number of tabs. If horizontal space limits the number of visible tabs, the trailing tab becomes a More tab in iOS and iPadOS, revealing the remaining items in a separate list. The More tab makes it harder for people to reach and notice content on tabs that are hidden, so limit scenarios in your app where this can happen." }, { "type": "paragraph", "text": "Don’t disable or hide tab bar buttons, even when their content is unavailable. Having tab bar buttons available in some cases but not others makes your app’s interface appear unstable and unpredictable. If a section is empty, explain why its content is unavailable." }, { "type": "paragraph", "text": "Include tab labels to help with navigation. A tab label appears beneath or beside a tab bar icon, and can aid navigation by clearly describing the type of content or functionality the tab contains. Use single words whenever possible." }, { "type": "paragraph", "text": "Consider using SF Symbols to provide familiar, scalable tab bar icons. When you use SF Symbols, tab bar icons automatically adapt to different contexts. For example, the tab bar can be regular or compact, depending on the device and orientation. Tab bar icons appear above tab labels in compact views, whereas in regular views, the icons and labels appear side by side. Prefer filled symbols or icons for consistency with the platform." }, { "type": "paragraph", "text": "If you’re creating custom tab bar icons, see Apple Design Resources for tab bar icon dimensions." }, { "type": "paragraph", "text": "Use a badge to indicate that critical information is available. You can display a badge — a red oval containing white text and either a number or an exclamation point — on a tab to indicate that there’s new or updated information in the section that warrants a person’s attention. Reserve badges for critical information so you don’t dilute their impact and meaning. For guidance, see Notifications." }, { "type": "paragraph", "text": "Avoid applying a similar color to tab labels and content layer backgrounds. If your app already has bright, colorful content in the content layer, prefer a monochromatic appearance for tab bars, or choose an accent color with sufficient visual differentiation. For more guidance, see Liquid Glass color." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for macOS. Not supported in watchOS." } ] }, { "heading": "iOS", "level": 3, "content": [ { "type": "paragraph", "text": "A tab bar floats above content at the bottom of the screen. Its items rest on a Liquid Glass background that allows content beneath to peek through." }, { "type": "paragraph", "text": "For tab bars with an attached accessory, like the MiniPlayer in Music, you can choose to minimize the tab bar and move the accessory inline with it when a person scrolls down. A person can exit the minimized state by tapping a tab or scrolling to the top of the view. For developer guidance, see TabBarMinimizeBehavior and UITabBarController.MinimizeBehavior." }, { "type": "paragraph", "text": "A tab bar with an attached accessory, expanded" }, { "type": "paragraph", "text": "A tab bar with an attached accessory, minimized" }, { "type": "paragraph", "text": "A tab bar can include a distinct search item at the trailing end. For guidance, see Search fields." } ] }, { "heading": "iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "The system displays a tab bar near the top of the screen. You can choose to have the tab bar appear as a fixed element, or with a button that converts it to a sidebar. For developer guidance, see tabBarOnly and sidebarAdaptable." }, { "type": "note", "text": "NoteTo present a sidebar without the option to convert it to a tab bar, use a navigation split view instead of a tab view. For guidance, see Sidebars." }, { "type": "paragraph", "text": "Prefer a tab bar for navigation. A tab bar provides access to the sections of your app that people use most. If your app is more complex, you can provide the option to convert the tab bar to a sidebar so people can access a wider set of navigation options." }, { "type": "paragraph", "text": "Let people customize the tab bar. In apps with a lot of sections that people might want to access, it can be useful to let people select items that they use frequently and add them to the tab bar, or remove items that they use less frequently. For example, in the Music app, a person can choose a favorite playlist to display in the tab bar. If you let people select their own tabs, aim for a default list of five or fewer to preserve continuity between compact and regular view sizes. For developer guidance, see TabViewCustomization and UITab.Placement." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "A tab bar is highly customizable. For example, you can:" }, { "type": "list", "items": [ "Specify a tint, color, or image for the tab bar background", "Choose a font for tab items, including a different font for the selected item", "Specify tints for selected and unselected items", "Add button icons, like settings and search" ] }, { "type": "paragraph", "text": "By default, a tab bar is translucent, and only the selected tab is opaque. When people use the remote to focus on the tab bar, the selected tab includes a drop shadow that emphasizes its selected state. The height of a tab bar is 68 points, and its top edge is 46 points from the top of the screen; you can’t change either of these values." }, { "type": "paragraph", "text": "If there are more items than can fit in the tab bar, the system truncates the rightmost item by applying a fade effect that begins at the right side of the tab bar. If there are enough items to cause scrolling, the system also applies a truncating fade effect that starts from the left side." }, { "type": "paragraph", "text": "Be aware of tab bar scrolling behaviors. By default, people can scroll the tab bar offscreen when the current tab contains a single main view. You can see examples of this behavior in the Watch Now, Movies, TV Show, Sports, and Kids tabs in the TV app. The exception is when a screen contains a split view, such as the TV app’s Library tab or an app’s Settings screen. In this case, the tab bar remains pinned at the top of the view while people scroll the content within the primary and secondary panes of the split view. Regardless of a tab’s contents, focus always returns to the tab bar at the top of the page when people press Menu on the remote." }, { "type": "paragraph", "text": "In a live-viewing app, organize tabs in a consistent way. For the best experience, organize content in live-streaming apps with tabs in the following order:" }, { "type": "list", "items": [ "Live content", "Cloud DVR or other recorded content", "Other content" ] }, { "type": "paragraph", "text": "For additional guidance, see Live-viewing apps." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In visionOS, a tab bar is always vertical, floating in a position that’s fixed relative to the window’s leading side. When people look at a tab bar, it automatically expands; to open a specific tab, people look at the tab and tap. While a tab bar is expanded, it can temporarily obscure the content behind it." }, { "type": "paragraph", "text": "Supply a symbol and a text label for each tab. A tab’s symbol is always visible in the tab bar. When people look at the tab bar, the system reveals tab labels, too. Even though the tab bar expands, you need to keep tab labels short so people can read them at a glance." }, { "type": "paragraph", "text": "Collapsed" }, { "type": "paragraph", "text": "Expanded" }, { "type": "paragraph", "text": "If it makes sense in your app, consider using a sidebar within a tab. If your app’s hierarchy is deep, you might want to use a sidebar to support secondary navigation within a tab. If you do this, be sure to prevent selections in the sidebar from changing which tab is currently open." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Tab views" }, { "type": "paragraph", "text": "Toolbars" }, { "type": "paragraph", "text": "Sidebars" }, { "type": "paragraph", "text": "Materials" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "TabView — SwiftUI" }, { "type": "paragraph", "text": "TabViewBottomAccessoryPlacement — SwiftUI" }, { "type": "paragraph", "text": "Enhancing your app’s content with tab navigation — SwiftUI" }, { "type": "paragraph", "text": "UITabBar — UIKit" }, { "type": "paragraph", "text": "Elevating your iPad app with a tab bar and sidebar — UIKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Updated guidance for Liquid Glass." ], [ "July 28, 2025", "Added guidance for Liquid Glass." ], [ "September 9, 2024", "Added art representing the tab bar in iPadOS 18." ], [ "August 6, 2024", "Updated with guidance for the tab bar in iPadOS 18." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/tab-bars#Best-practices" }, { "title": "toolbar", "url": "/design/human-interface-guidelines/toolbars" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Notifications", "url": "/design/human-interface-guidelines/notifications" }, { "title": "Liquid Glass color", "url": "/design/human-interface-guidelines/color#Liquid-Glass-color" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/tab-bars#Platform-considerations" }, { "title": "iOS", "url": "/design/human-interface-guidelines/tab-bars#iOS" }, { "title": "Liquid Glass", "url": "/design/human-interface-guidelines/materials#Liquid-Glass" }, { "title": "Search fields", "url": "/design/human-interface-guidelines/search-fields" }, { "title": "iPadOS", "url": "/design/human-interface-guidelines/tab-bars#iPadOS" }, { "title": "Sidebars", "url": "/design/human-interface-guidelines/sidebars" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/tab-bars#tvOS" }, { "title": "Live-viewing apps", "url": "/design/human-interface-guidelines/live-viewing-apps" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/tab-bars#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/tab-bars#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/tab-bars#Related" }, { "title": "Tab views", "url": "/design/human-interface-guidelines/tab-views" }, { "title": "Materials", "url": "/design/human-interface-guidelines/materials" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/tab-bars#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/tab-bars#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/tab-bars#Change-log" } ], "image_count": 0 }, { "title": "Toggles", "url": "https://developer.apple.com/design/human-interface-guidelines/toggles", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "A toggle can have various styles, such as switch and checkbox, and different platforms can use these styles in different ways. For guidance, see Platform considerations." }, { "type": "paragraph", "text": "In addition to toggles, all platforms also support buttons that behave like toggles by using a different appearance for each state. For developer guidance, see ToggleStyle." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Use a toggle to help people choose between two opposing values that affect the state of content or a view. A toggle always lets people manage the state of something, so if you need to support other types of actions — such as choosing from a list of items — use a different component, like a pop-up button." }, { "type": "paragraph", "text": "Clearly identify the setting, view, or content the toggle affects. In general, the surrounding context provides enough information for people to understand what they’re turning on or off. In some cases, often in macOS apps, you can also supply a label to describe the state the toggle controls. If you use a button that behaves like a toggle, you generally use an interface icon that communicates its purpose, and you update its appearance — typically by changing the background — based on the current state." }, { "type": "paragraph", "text": "Make sure the visual differences in a toggle’s state are obvious. For example, you might add or remove a color fill, show or hide the background shape, or change the inner details you display — like a checkmark or dot — to show that a toggle is on or off. Avoid relying solely on different colors to communicate state, because not everyone can perceive the differences." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for tvOS, visionOS, or watchOS." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "Use the switch toggle style only in a list row. You don’t need to supply a label in this situation because the content in the row provides the context for the state the switch controls." }, { "type": "paragraph", "text": "Change the default color of a switch only if necessary. The default green color tends to work well in most cases, but you might want to use your app’s accent color instead. Be sure to use a color that provides enough contrast with the uncolored appearance to be perceptible." }, { "type": "paragraph", "text": "Standard switch color" }, { "type": "paragraph", "text": "Custom switch color" }, { "type": "paragraph", "text": "Outside of a list, use a button that behaves like a toggle, not a switch. For example, the Phone app uses a toggle on the filter button to let users filter their recent calls. The app adds a blue highlight to indicate when the toggle is active, and removes it when the toggle is inactive." }, { "type": "paragraph", "text": "The Phone app uses a toggle to switch between all recent calls and various filter options. When someone chooses a filter, the toggle appears with a custom background drawn behind the symbol." }, { "type": "paragraph", "text": "When someone returns to the main Recents view, the toggle appears without anything behind the symbol." }, { "type": "paragraph", "text": "Avoid supplying a label that explains the button’s purpose. The interface icon you create — combined with the alternative background appearances you supply — help people understand what the button does. For developer guidance, see changesSelectionAsPrimaryAction." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "In addition to the switch toggle style, macOS supports the checkbox style and also defines radio buttons that can provide similar behaviors." }, { "type": "paragraph", "text": "Use switches, checkboxes, and radio buttons in the window body, not the window frame. In particular, avoid using these components in a toolbar or status bar." } ] }, { "heading": "Switches", "level": 4, "content": [ { "type": "paragraph", "text": "Prefer a switch for settings that you want to emphasize. A switch has more visual weight than a checkbox, so it looks better when it controls more functionality than a checkbox typically does. For example, you might use a switch to let people turn on or off a group of settings, instead of just one setting. For developer guidance, see switch." }, { "type": "paragraph", "text": "Within a grouped form, consider using a mini switch to control the setting in a single row. The height of a mini switch is similar to the height of buttons and other controls, resulting in rows that have a consistent height. If you need to present a hierarchy of settings within a grouped form, you can use a regular switch for the primary setting and mini switches for the subordinate settings. For developer guidance, see GroupedFormStyle and ControlSize." }, { "type": "paragraph", "text": "In general, don’t replace a checkbox with a switch. If you’re already using a checkbox in your interface, it’s probably best to keep using it." } ] }, { "heading": "Checkboxes", "level": 4, "content": [ { "type": "paragraph", "text": "A checkbox is a small, square button that’s empty when the button is off, contains a checkmark when the button is on, and can contain a dash when the button’s state is mixed. Typically, a checkbox includes a title on its trailing side. In an editable checklist, a checkbox can appear without a title or any additional content." }, { "type": "paragraph", "text": "Use a checkbox instead of a switch if you need to present a hierarchy of settings. The visual style of checkboxes helps them align well and communicate grouping. By using alignment — generally along the leading edge of the checkboxes — and indentation, you can show dependencies, such as when the state of a checkbox governs the state of subordinate checkboxes." }, { "type": "paragraph", "text": "Consider using radio buttons if you need to present a set of more than two mutually exclusive options. When people need to choose from options in addition to just “on” or “off,” using multiple radio buttons can help you clarify each option with a unique label." }, { "type": "paragraph", "text": "Consider using a label to introduce a group of checkboxes if their relationship isn’t clear. Describe the set of options, and align the label’s baseline with the first checkbox in the group." }, { "type": "paragraph", "text": "Accurately reflect a checkbox’s state in its appearance. A checkbox’s state can be on, off, or mixed. If you use a checkbox to globally turn on and off multiple subordinate checkboxes, show a mixed state when the subordinate checkboxes have different states. For example, you might need to present a text-style setting that turns all styles on or off, but also lets people choose a subset of individual style settings like bold, italic, or underline. For developer guidance, see allowsMixedState." }, { "type": "paragraph", "text": "On" }, { "type": "paragraph", "text": "Off" }, { "type": "paragraph", "text": "Mixed" } ] }, { "heading": "Radio buttons", "level": 4, "content": [ { "type": "paragraph", "text": "A radio button is a small, circular button followed by a label. Typically displayed in groups of two to five, radio buttons present a set of mutually exclusive choices." }, { "type": "paragraph", "text": "A radio button’s state is either selected (a filled circle) or deselected (an empty circle). Although a radio button can also display a mixed state (indicated by a dash), this state is rarely useful because you can communicate multiple states by using additional radio buttons. If you need to show that a setting or item has a mixed state, consider using a checkbox instead." }, { "type": "paragraph", "text": "Selected" }, { "type": "paragraph", "text": "Deselected" }, { "type": "paragraph", "text": "Prefer a set of radio buttons to present mutually exclusive options. If you need to let people choose multiple options in a set, use checkboxes instead." }, { "type": "paragraph", "text": "Avoid listing too many radio buttons in a set. A long list of radio buttons takes up a lot of space in the interface and can be overwhelming. If you need to present more than about five options, consider using a component like a pop-up button instead." }, { "type": "paragraph", "text": "To present a single setting that can be on or off, prefer a checkbox. Although a single radio button can also turn something on or off, the presence or absence of the checkmark in a checkbox can make the current state easier to understand at a glance. In rare cases where a single checkbox doesn’t clearly communicate the opposing states, you can use a pair of radio buttons, each with a label that specifies the state it controls." }, { "type": "paragraph", "text": "Use consistent spacing when you display radio buttons horizontally. Measure the space needed to accommodate the longest button label, and use that measurement consistently." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Layout" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Toggle — SwiftUI" }, { "type": "paragraph", "text": "UISwitch — UIKit" }, { "type": "paragraph", "text": "NSButton.ButtonType.toggle — AppKit" }, { "type": "paragraph", "text": "NSSwitch — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "March 29, 2024", "Enhanced guidance for using switches in macOS apps, clarified when a checkbox has a title, and added artwork for radio buttons." ], [ "September 12, 2023", "Updated artwork." ] ] } ] } ], "platforms": [], "related": [ { "title": "Platform considerations", "url": "/design/human-interface-guidelines/toggles#Platform-considerations" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/toggles#Best-practices" }, { "title": "pop-up button", "url": "/design/human-interface-guidelines/pop-up-buttons" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/toggles#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/toggles#macOS" }, { "title": "Switches", "url": "/design/human-interface-guidelines/toggles#Switches" }, { "title": "Checkboxes", "url": "/design/human-interface-guidelines/toggles#Checkboxes" }, { "title": "Radio buttons", "url": "/design/human-interface-guidelines/toggles#Radio-buttons" }, { "title": "Resources", "url": "/design/human-interface-guidelines/toggles#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/toggles#Related" }, { "title": "Layout", "url": "/design/human-interface-guidelines/layout" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/toggles#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/toggles#Change-log" } ], "image_count": 0 }, { "title": "Typography", "url": "https://developer.apple.com/design/human-interface-guidelines/typography", "category": "foundations", "summary": "", "sections": [ { "heading": "Ensuring legibility", "level": 2, "content": [ { "type": "paragraph", "text": "Use font sizes that most people can read easily. People need to be able to read your content at various viewing distances and under a variety of conditions. Follow the recommended default and minimum text sizes for each platform — for both custom and system fonts — to ensure your text is legible on all devices. Keep in mind that font weight can also impact how easy text is to read. If you use a custom font with a thin weight, aim for larger than the recommended sizes to increase legibility." }, { "type": "table", "rows": [ [ "Platform", "Default size", "Minimum size" ], [ "iOS, iPadOS", "17 pt", "11 pt" ], [ "macOS", "13 pt", "10 pt" ], [ "tvOS", "29 pt", "23 pt" ], [ "visionOS", "17 pt", "12 pt" ], [ "watchOS", "16 pt", "12 pt" ] ] }, { "type": "paragraph", "text": "Test legibility in different contexts. For example, you need to test game text for legibility on each platform on which your game runs. If testing shows that some of your text is difficult to read, consider using a larger type size, increasing contrast by modifying the text or background colors, or using typefaces designed for optimized legibility, like the system fonts." }, { "type": "paragraph", "text": "Testing a game on a new platform can show where text is hard to read." }, { "type": "paragraph", "text": "Increasing text size and adding visible background shapes can help make text easier to read." }, { "type": "paragraph", "text": "In general, avoid light font weights. For example, if you’re using system-provided fonts, prefer Regular, Medium, Semibold, or Bold font weights, and avoid Ultralight, Thin, and Light font weights, which can be difficult to see, especially when text is small." } ] }, { "heading": "Conveying hierarchy", "level": 2, "content": [ { "type": "paragraph", "text": "Adjust font weight, size, and color as needed to emphasize important information and help people visualize hierarchy. Be sure to maintain the relative hierarchy and visual distinction of text elements when people adjust text sizes." }, { "type": "paragraph", "text": "Minimize the number of typefaces you use, even in a highly customized interface. Mixing too many different typefaces can obscure your information hierarchy and hinder readability, in addition to making an interface feel internally inconsistent or poorly designed." }, { "type": "paragraph", "text": "Prioritize important content when responding to text-size changes. Not all content is equally important. When someone chooses a larger text size, they typically want to make the content they care about easier to read; they don’t always want to increase the size of every word on the screen. For example, when people increase text size to read the content in a tabbed window, they don’t expect the tab titles to increase in size. Similarly, in a game, people are often more interested in a character’s dialog than in transient hit-damage values." } ] }, { "heading": "Using system fonts", "level": 2, "content": [ { "type": "paragraph", "text": "Apple provides two typeface families that support an extensive range of weights, sizes, styles, and languages." }, { "type": "paragraph", "text": "San Francisco (SF) is a sans serif typeface family that includes the SF Pro, SF Compact, SF Arabic, SF Armenian, SF Georgian, SF Hebrew, and SF Mono variants." }, { "type": "paragraph", "text": "The system also offers SF Pro, SF Compact, SF Arabic, SF Armenian, SF Georgian, and SF Hebrew in rounded variants you can use to coordinate text with the appearance of soft or rounded UI elements, or to provide an alternative typographic voice." }, { "type": "paragraph", "text": "New York (NY) is a serif typeface family designed to work well by itself and alongside the SF fonts." }, { "type": "paragraph", "text": "You can download the San Francisco and New York fonts here." }, { "type": "paragraph", "text": "The system provides the SF and NY fonts in the variable font format, which combines different font styles together in one file, and supports interpolation between styles to create intermediate ones." }, { "type": "note", "text": "NoteVariable fonts support optical sizing, which refers to the adjustment of different typographic designs to fit different sizes. On all platforms, the system fonts support dynamic optical sizes, which merge discrete optical sizes (like Text and Display) and weights into a single, continuous design, letting the system interpolate each glyph or letterform to produce a structure that’s precisely adapted to the point size. With dynamic optical sizes, you don’t need to use discrete optical sizes unless you’re working with a design tool that doesn’t support all the features of the variable font format." }, { "type": "paragraph", "text": "To help you define visual hierarchies and create clear and legible designs in many different sizes and contexts, the system fonts are available in a variety of weights, ranging from Ultralight to Black, and — in the case of SF — several widths, including Condensed and Expanded. Because SF Symbols use equivalent weights, you can achieve precise weight matching between symbols and adjacent text, regardless of the size or style you choose." }, { "type": "note", "text": "NoteSF Symbols provides a comprehensive library of symbols that integrate seamlessly with the San Francisco system font, automatically aligning with text in all weights and sizes. Consider using symbols when you need to convey a concept or depict an object, especially within text." }, { "type": "paragraph", "text": "The system defines a set of typographic attributes — called text styles — that work with both typeface families. A text style specifies a combination of font weight, point size, and leading values for each text size. For example, the body text style uses values that support a comfortable reading experience over multiple lines of text, while the headline style assigns a font size and weight that help distinguish a heading from surrounding content. Taken together, the text styles form a typographic hierarchy you can use to express the different levels of importance in your content. Text styles also allow text to scale proportionately when people change the system’s text size or make accessibility adjustments, like turning on Larger Text in Accessibility settings." }, { "type": "paragraph", "text": "Consider using the built-in text styles. The system-defined text styles give you a convenient and consistent way to convey your information hierarchy through font size and weight. Using text styles with the system fonts also ensures support for Dynamic Type and larger accessibility type sizes (where available), which let people choose the text size that works for them. For guidance, see Supporting Dynamic Type." }, { "type": "paragraph", "text": "Modify the built-in text styles if necessary. System APIs define font adjustments — called symbolic traits — that let you modify some aspects of a text style. For example, the bold trait adds weight to text, letting you create another level of hierarchy. You can also use symbolic traits to adjust leading if you need to improve readability or conserve space. For example, when you display text in wide columns or long passages, more space between lines (loose leading) can make it easier for people to keep their place while moving from one line to the next. Conversely, if you need to display multiple lines of text in an area where height is constrained — for example, in a list row — decreasing the space between lines (tight leading) can help the text fit well. If you need to display three or more lines of text, avoid tight leading even in areas where height is limited. For developer guidance, see leading(_:)." }, { "type": "note", "text": "Developer noteYou can use the constants defined in Font.Design to access all system fonts — don’t embed system fonts in your app or game. For example, use Font.Design.default to get the system font on all platforms; use Font.Design.serif to get the New York font." }, { "type": "paragraph", "text": "If necessary, adjust tracking in interface mockups. In a running app, the system font dynamically adjusts tracking at every point size. To produce an accurate interface mockup of an interface that uses the variable system fonts, you don’t have to choose a discrete optical size at certain point sizes, but you might need to adjust the tracking. For guidance, see Tracking values." } ] }, { "heading": "Using custom fonts", "level": 2, "content": [ { "type": "paragraph", "text": "Make sure custom fonts are legible. People need to be able to read your custom font easily at various viewing distances and under a variety of conditions. While using a custom font, be guided by the recommended minimum font sizes for various styles and weights in Specifications." }, { "type": "paragraph", "text": "Implement accessibility features for custom fonts. System fonts automatically support Dynamic Type (where available) and respond when people turn on accessibility features, such as Bold Text. If you use a custom font, make sure it implements the same behaviors. For developer guidance, see Applying custom fonts to text. In a Unity-based game, you can use Apple’s Unity plug-ins to support Dynamic Type. If the plug-in isn’t appropriate for your game, be sure to let players adjust text size in other ways." } ] }, { "heading": "Supporting Dynamic Type", "level": 2, "content": [ { "type": "paragraph", "text": "Dynamic Type is a system-level feature in iOS, iPadOS, tvOS, visionOS, and watchOS that lets people adjust the size of visible text on their device to ensure readability and comfort. For related guidance, see Accessibility." }, { "type": "paragraph", "text": "Mail content at the default text size" }, { "type": "paragraph", "text": "Mail content at the largest accessibility text size" }, { "type": "paragraph", "text": "For a list of available Dynamic Type sizes, see Specifications. You can also download Dynamic Type size tables in the Apple Design Resources for each platform." }, { "type": "paragraph", "text": "For developer guidance, see Text input and output. To support Dynamic Type in Unity-based games, use Apple’s Unity plug-ins." }, { "type": "paragraph", "text": "Make sure your app’s layout adapts to all font sizes. Verify that your design scales, and that text and glyphs are legible at all font sizes. On iPhone or iPad, turn on Larger Accessibility Text Sizes in Settings > Accessibility > Display & Text Size > Larger Text, and confirm that your app remains comfortably readable." }, { "type": "paragraph", "text": "Increase the size of meaningful interface icons as font size increases. If you use interface icons to communicate important information, make sure they’re easy to view at larger font sizes too. When you use SF Symbols, you get icons that scale automatically with Dynamic Type size changes." }, { "type": "paragraph", "text": "Keep text truncation to a minimum as font size increases. In general, aim to display as much useful text at the largest accessibility font size as you do at the largest standard font size. Avoid truncating text in scrollable regions unless people can open a separate view to read the rest of the content. You can prevent text truncation in a label by configuring it to use as many lines as needed to display a useful amount of text. For developer guidance, see numberOfLines." }, { "type": "paragraph", "text": "Consider adjusting your layout at large font sizes. When font size increases in a horizontally constrained context, inline items (like glyphs and timestamps) and container boundaries can crowd text and cause truncation or overlapping. To improve readability, consider using a stacked layout where text appears above secondary items. Multicolumn text can also be less readable at large sizes due to horizontal space constraints. Reduce the number of columns when the font size increases to avoid truncation and enhance readability. For developer guidance, see isAccessibilityCategory." }, { "type": "paragraph", "text": "Maintain a consistent information hierarchy regardless of the current font size. For example, keep primary elements toward the top of a view even when the font size is very large, so that people don’t lose track of these elements." } ] }, { "heading": "iOS, iPadOS", "level": 3, "content": [ { "type": "paragraph", "text": "SF Pro is the system font in iOS and iPadOS. iOS and iPadOS apps can also use NY." } ] }, { "heading": "macOS", "level": 3, "content": [ { "type": "paragraph", "text": "SF Pro is the system font in macOS. NY is available for Mac apps built with Mac Catalyst. macOS doesn’t support Dynamic Type." }, { "type": "paragraph", "text": "When necessary, use dynamic system font variants to match the text in standard controls. Dynamic system font variants give your text the same look and feel of the text that appears in system-provided controls. Use the variants listed below to achieve a look that’s consistent with other apps on the platform." }, { "type": "table", "rows": [ [ "Dynamic font variant", "API" ], [ "Control content", "controlContentFont(ofSize:)" ], [ "Label", "labelFont(ofSize:)" ], [ "Menu", "menuFont(ofSize:)" ], [ "Menu bar", "menuBarFont(ofSize:)" ], [ "Message", "messageFont(ofSize:)" ], [ "Palette", "paletteFont(ofSize:)" ], [ "Title", "titleBarFont(ofSize:)" ], [ "Tool tips", "toolTipsFont(ofSize:)" ], [ "Document text (user)", "userFont(ofSize:)" ], [ "Monospaced document text (user fixed pitch)", "userFixedPitchFont(ofSize:)" ], [ "Bold system font", "boldSystemFont(ofSize:)" ], [ "System font", "systemFont(ofSize:)" ] ] } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "SF Pro is the system font in tvOS, and apps can also use NY." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "SF Pro is the system font in visionOS. If you use NY, you need to specify the type styles you want." }, { "type": "paragraph", "text": "visionOS uses bolder versions of the Dynamic Type body and title styles and it introduces Extra Large Title 1 and Extra Large Title 2 for wide, editorial-style layouts. For guidance using vibrancy to indicate hierarchy in text and symbols, see Materials > visionOS." }, { "type": "paragraph", "text": "In general, prefer 2D text. The more visual depth text characters have, the more difficult they can be to read. Although a small amount of 3D text can provide a fun visual element that draws people’s attention, if you’re going to display content that people need to read and understand, prefer using text that has little or no visual depth." }, { "type": "paragraph", "text": "Make sure text looks good and remains legible when people scale it. Use a text style that makes the text look good at full scale, then test it for legibility at different scales." }, { "type": "paragraph", "text": "Maximize the contrast between text and the background of its container. By default, the system displays text in white, because this color tends to provide a strong contrast with the default system background material, making text easier to read. If you want to use a different text color, be sure to test it in a variety of contexts." }, { "type": "paragraph", "text": "If you need to display text that’s not on a background, consider making it bold to improve legibility. In this situation, you generally want to avoid adding shadows to increase text contrast. The current space might not include a visual surface on which to cast an accurate shadow, and you can’t predict the size and density of shadow that would work well with a person’s current Environment." }, { "type": "paragraph", "text": "Keep text facing people as much as possible. If you display text that’s associated with a point in space, such as a label for a 3D object, you generally want to use billboarding — that is, you want the text to face the wearer regardless of how they or the object move. If you don’t rotate text to remain facing the wearer, the text can become impossible to read because people may view it from the side or a highly oblique angle. For example, imagine a virtual lamp that appears to be on a physical desk with a label anchored directly above it. For the text to remain readable, the label needs to rotate around the y-axis as people move around the desk; in other words, the baseline of the text needs to remain perpendicular to the person’s line of sight." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "SF Compact is the system font in watchOS, and apps can also use NY. In complications, watchOS uses SF Compact Rounded." } ] }, { "heading": "Specifications", "level": 2, "content": [ { "type": "paragraph", "text": "You can display emphasized variants of system text styles using symbolic traits. In SwiftUI, use the bold() modifier; in UIKit, use traitBold in the UIFontDescriptor API. The emphasized weights can be medium, semibold, bold, or heavy. The following specifications include the emphasized weight for each text style." } ] }, { "heading": "xSmall", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "31", "38", "Bold" ], [ "Title 1", "Regular", "25", "31", "Bold" ], [ "Title 2", "Regular", "19", "24", "Bold" ], [ "Title 3", "Regular", "17", "22", "Semibold" ], [ "Headline", "Semibold", "14", "19", "Semibold" ], [ "Body", "Regular", "14", "19", "Semibold" ], [ "Callout", "Regular", "13", "18", "Semibold" ], [ "Subhead", "Regular", "12", "16", "Semibold" ], [ "Footnote", "Regular", "12", "16", "Semibold" ], [ "Caption 1", "Regular", "11", "13", "Semibold" ], [ "Caption 2", "Regular", "11", "13", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "Small", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "32", "39", "Bold" ], [ "Title 1", "Regular", "26", "32", "Bold" ], [ "Title 2", "Regular", "20", "25", "Bold" ], [ "Title 3", "Regular", "18", "23", "Semibold" ], [ "Headline", "Semibold", "15", "20", "Semibold" ], [ "Body", "Regular", "15", "20", "Semibold" ], [ "Callout", "Regular", "14", "19", "Semibold" ], [ "Subhead", "Regular", "13", "18", "Semibold" ], [ "Footnote", "Regular", "12", "16", "Semibold" ], [ "Caption 1", "Regular", "11", "13", "Semibold" ], [ "Caption 2", "Regular", "11", "13", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "Medium", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "33", "40", "Bold" ], [ "Title 1", "Regular", "27", "33", "Bold" ], [ "Title 2", "Regular", "21", "26", "Bold" ], [ "Title 3", "Regular", "19", "24", "Semibold" ], [ "Headline", "Semibold", "16", "21", "Semibold" ], [ "Body", "Regular", "16", "21", "Semibold" ], [ "Callout", "Regular", "15", "20", "Semibold" ], [ "Subhead", "Regular", "14", "19", "Semibold" ], [ "Footnote", "Regular", "12", "16", "Semibold" ], [ "Caption 1", "Regular", "11", "13", "Semibold" ], [ "Caption 2", "Regular", "11", "13", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "Large (default)", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "34", "41", "Bold" ], [ "Title 1", "Regular", "28", "34", "Bold" ], [ "Title 2", "Regular", "22", "28", "Bold" ], [ "Title 3", "Regular", "20", "25", "Semibold" ], [ "Headline", "Semibold", "17", "22", "Semibold" ], [ "Body", "Regular", "17", "22", "Semibold" ], [ "Callout", "Regular", "16", "21", "Semibold" ], [ "Subhead", "Regular", "15", "20", "Semibold" ], [ "Footnote", "Regular", "13", "18", "Semibold" ], [ "Caption 1", "Regular", "12", "16", "Semibold" ], [ "Caption 2", "Regular", "11", "13", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "xLarge", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "36", "43", "Bold" ], [ "Title 1", "Regular", "30", "37", "Bold" ], [ "Title 2", "Regular", "24", "30", "Bold" ], [ "Title 3", "Regular", "22", "28", "Semibold" ], [ "Headline", "Semibold", "19", "24", "Semibold" ], [ "Body", "Regular", "19", "24", "Semibold" ], [ "Callout", "Regular", "18", "23", "Semibold" ], [ "Subhead", "Regular", "17", "22", "Semibold" ], [ "Footnote", "Regular", "15", "20", "Semibold" ], [ "Caption 1", "Regular", "14", "19", "Semibold" ], [ "Caption 2", "Regular", "13", "18", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "xxLarge", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "38", "46", "Bold" ], [ "Title 1", "Regular", "32", "39", "Bold" ], [ "Title 2", "Regular", "26", "32", "Bold" ], [ "Title 3", "Regular", "24", "30", "Semibold" ], [ "Headline", "Semibold", "21", "26", "Semibold" ], [ "Body", "Regular", "21", "26", "Semibold" ], [ "Callout", "Regular", "20", "25", "Semibold" ], [ "Subhead", "Regular", "19", "24", "Semibold" ], [ "Footnote", "Regular", "17", "22", "Semibold" ], [ "Caption 1", "Regular", "16", "21", "Semibold" ], [ "Caption 2", "Regular", "15", "20", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "xxxLarge", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "40", "48", "Bold" ], [ "Title 1", "Regular", "34", "41", "Bold" ], [ "Title 2", "Regular", "28", "34", "Bold" ], [ "Title 3", "Regular", "26", "32", "Semibold" ], [ "Headline", "Semibold", "23", "29", "Semibold" ], [ "Body", "Regular", "23", "29", "Semibold" ], [ "Callout", "Regular", "22", "28", "Semibold" ], [ "Subhead", "Regular", "21", "28", "Semibold" ], [ "Footnote", "Regular", "19", "24", "Semibold" ], [ "Caption 1", "Regular", "18", "23", "Semibold" ], [ "Caption 2", "Regular", "17", "22", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "AX1", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "44", "52", "Bold" ], [ "Title 1", "Regular", "38", "46", "Bold" ], [ "Title 2", "Regular", "34", "41", "Bold" ], [ "Title 3", "Regular", "31", "38", "Semibold" ], [ "Headline", "Semibold", "28", "34", "Semibold" ], [ "Body", "Regular", "28", "34", "Semibold" ], [ "Callout", "Regular", "26", "32", "Semibold" ], [ "Subhead", "Regular", "25", "31", "Semibold" ], [ "Footnote", "Regular", "23", "29", "Semibold" ], [ "Caption 1", "Regular", "22", "28", "Semibold" ], [ "Caption 2", "Regular", "20", "25", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "AX2", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "48", "57", "Bold" ], [ "Title 1", "Regular", "43", "51", "Bold" ], [ "Title 2", "Regular", "39", "47", "Bold" ], [ "Title 3", "Regular", "37", "44", "Semibold" ], [ "Headline", "Semibold", "33", "40", "Semibold" ], [ "Body", "Regular", "33", "40", "Semibold" ], [ "Callout", "Regular", "32", "39", "Semibold" ], [ "Subhead", "Regular", "30", "37", "Semibold" ], [ "Footnote", "Regular", "27", "33", "Semibold" ], [ "Caption 1", "Regular", "26", "32", "Semibold" ], [ "Caption 2", "Regular", "24", "30", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "AX3", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "52", "61", "Bold" ], [ "Title 1", "Regular", "48", "57", "Bold" ], [ "Title 2", "Regular", "44", "52", "Bold" ], [ "Title 3", "Regular", "43", "51", "Semibold" ], [ "Headline", "Semibold", "40", "48", "Semibold" ], [ "Body", "Regular", "40", "48", "Semibold" ], [ "Callout", "Regular", "38", "46", "Semibold" ], [ "Subhead", "Regular", "36", "43", "Semibold" ], [ "Footnote", "Regular", "33", "40", "Semibold" ], [ "Caption 1", "Regular", "32", "39", "Semibold" ], [ "Caption 2", "Regular", "29", "35", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "AX4", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "56", "66", "Bold" ], [ "Title 1", "Regular", "53", "62", "Bold" ], [ "Title 2", "Regular", "50", "59", "Bold" ], [ "Title 3", "Regular", "49", "58", "Semibold" ], [ "Headline", "Semibold", "47", "56", "Semibold" ], [ "Body", "Regular", "47", "56", "Semibold" ], [ "Callout", "Regular", "44", "52", "Semibold" ], [ "Subhead", "Regular", "42", "50", "Semibold" ], [ "Footnote", "Regular", "38", "46", "Semibold" ], [ "Caption 1", "Regular", "37", "44", "Semibold" ], [ "Caption 2", "Regular", "34", "41", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "AX5", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "60", "70", "Bold" ], [ "Title 1", "Regular", "58", "68", "Bold" ], [ "Title 2", "Regular", "56", "66", "Bold" ], [ "Title 3", "Regular", "55", "65", "Semibold" ], [ "Headline", "Semibold", "53", "62", "Semibold" ], [ "Body", "Regular", "53", "62", "Semibold" ], [ "Callout", "Regular", "51", "60", "Semibold" ], [ "Subhead", "Regular", "49", "58", "Semibold" ], [ "Footnote", "Regular", "44", "52", "Semibold" ], [ "Caption 1", "Regular", "43", "51", "Semibold" ], [ "Caption 2", "Regular", "40", "48", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "macOS built-in text styles", "level": 3, "content": [ { "type": "table", "rows": [ [ "Text style", "Weight", "Size (points)", "Line height (points)", "Emphasized weight" ], [ "Large Title", "Regular", "26", "32", "Bold" ], [ "Title 1", "Regular", "22", "26", "Bold" ], [ "Title 2", "Regular", "17", "22", "Bold" ], [ "Title 3", "Regular", "15", "20", "Semibold" ], [ "Headline", "Bold", "13", "16", "Heavy" ], [ "Body", "Regular", "13", "16", "Semibold" ], [ "Callout", "Regular", "12", "15", "Semibold" ], [ "Subheadline", "Regular", "11", "14", "Semibold" ], [ "Footnote", "Regular", "10", "13", "Semibold" ], [ "Caption 1", "Regular", "10", "13", "Medium" ], [ "Caption 2", "Medium", "10", "13", "Semibold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 144 ppi for @2x designs." } ] }, { "heading": "tvOS built-in text styles", "level": 3, "content": [ { "type": "table", "rows": [ [ "Text style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Title 1", "Medium", "76", "96", "Bold" ], [ "Title 2", "Medium", "57", "66", "Bold" ], [ "Title 3", "Medium", "48", "56", "Bold" ], [ "Headline", "Medium", "38", "46", "Bold" ], [ "Subtitle 1", "Regular", "38", "46", "Medium" ], [ "Callout", "Medium", "31", "38", "Bold" ], [ "Body", "Medium", "29", "36", "Bold" ], [ "Caption 1", "Medium", "25", "32", "Bold" ], [ "Caption 2", "Medium", "23", "30", "Bold" ] ] }, { "type": "paragraph", "text": "Point size based on image resolution of 72 ppi for @1x and 144 ppi for @2x designs." } ] }, { "heading": "xSmall", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "30", "32.5", "Bold" ], [ "Title 1", "Regular", "28", "30.5", "Semibold" ], [ "Title 2", "Regular", "24", "26.5", "Semibold" ], [ "Title 3", "Regular", "17", "19.5", "Semibold" ], [ "Headline", "Semibold", "14", "16.5", "Semibold" ], [ "Body", "Regular", "14", "16.5", "Semibold" ], [ "Caption 1", "Regular", "13", "15.5", "Semibold" ], [ "Caption 2", "Regular", "12", "14.5", "Semibold" ], [ "Footnote 1", "Regular", "11", "13.5", "Semibold" ], [ "Footnote 2", "Regular", "10", "12.5", "Semibold" ] ] } ] }, { "heading": "Small (default 38mm)", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "32", "34.5", "Bold" ], [ "Title 1", "Regular", "30", "32.5", "Semibold" ], [ "Title 2", "Regular", "26", "28.5", "Semibold" ], [ "Title 3", "Regular", "18", "20.5", "Semibold" ], [ "Headline", "Semibold", "15", "17.5", "Semibold" ], [ "Body", "Regular", "15", "17.5", "Semibold" ], [ "Caption 1", "Regular", "14", "16.5", "Semibold" ], [ "Caption 2", "Regular", "13", "15.5", "Semibold" ], [ "Footnote 1", "Regular", "12", "14.5", "Semibold" ], [ "Footnote 2", "Regular", "11", "13.5", "Semibold" ] ] } ] }, { "heading": "Large (default 40mm/41mm/42mm)", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "36", "38.5", "Bold" ], [ "Title 1", "Regular", "34", "36.5", "Semibold" ], [ "Title 2", "Regular", "27", "30.5", "Semibold" ], [ "Title 3", "Regular", "19", "21.5", "Semibold" ], [ "Headline", "Semibold", "16", "18.5", "Semibold" ], [ "Body", "Regular", "16", "18.5", "Semibold" ], [ "Caption 1", "Regular", "15", "17.5", "Semibold" ], [ "Caption 2", "Regular", "14", "16.5", "Semibold" ], [ "Footnote 1", "Regular", "13", "15.5", "Semibold" ], [ "Footnote 2", "Regular", "12", "14.5", "Semibold" ] ] } ] }, { "heading": "xLarge (default 44mm/45mm/49mm)", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "40", "42.5", "Bold" ], [ "Title 1", "Regular", "38", "40.5", "Semibold" ], [ "Title 2", "Regular", "30", "32.5", "Semibold" ], [ "Title 3", "Regular", "20", "22.5", "Semibold" ], [ "Headline", "Semibold", "17", "19.5", "Semibold" ], [ "Body", "Regular", "17", "19.5", "Semibold" ], [ "Caption 1", "Regular", "16", "18.5", "Semibold" ], [ "Caption 2", "Regular", "15", "17.5", "Semibold" ], [ "Footnote 1", "Regular", "14", "16.5", "Semibold" ], [ "Footnote 2", "Regular", "13", "15.5", "Semibold" ] ] } ] }, { "heading": "xxLarge", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "41", "43.5", "Bold" ], [ "Title 1", "Regular", "39", "41.5", "Semibold" ], [ "Title 2", "Regular", "31", "33.5", "Semibold" ], [ "Title 3", "Regular", "21", "23.5", "Semibold" ], [ "Headline", "Semibold", "18", "20.5", "Semibold" ], [ "Body", "Regular", "18", "20.5", "Semibold" ], [ "Caption 1", "Regular", "17", "19.5", "Semibold" ], [ "Caption 2", "Regular", "15", "18.5", "Semibold" ], [ "Footnote 1", "Regular", "15", "17.5", "Semibold" ], [ "Footnote 2", "Regular", "14", "16.5", "Semibold" ] ] } ] }, { "heading": "xxxLarge", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "42", "44.5", "Bold" ], [ "Title 1", "Regular", "40", "42.5", "Semibold" ], [ "Title 2", "Regular", "32", "34.5", "Semibold" ], [ "Title 3", "Regular", "22", "24.5", "Semibold" ], [ "Headline", "Semibold", "19", "21.5", "Semibold" ], [ "Body", "Regular", "19", "21.5", "Semibold" ], [ "Caption 1", "Regular", "18", "20.5", "Semibold" ], [ "Caption 2", "Regular", "17", "19.5", "Semibold" ], [ "Footnote 1", "Regular", "16", "18.5", "Semibold" ], [ "Footnote 2", "Regular", "15", "17.5", "Semibold" ] ] } ] }, { "heading": "AX1", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "44", "46.5", "Bold" ], [ "Title 1", "Regular", "42", "44.5", "Semibold" ], [ "Title 2", "Regular", "34", "41", "Semibold" ], [ "Title 3", "Regular", "24", "26.5", "Semibold" ], [ "Headline", "Semibold", "21", "23.5", "Semibold" ], [ "Body", "Regular", "21", "23.5", "Semibold" ], [ "Caption 1", "Regular", "18", "20.5", "Semibold" ], [ "Caption 2", "Regular", "17", "19.5", "Semibold" ], [ "Footnote 1", "Regular", "16", "18.5", "Semibold" ], [ "Footnote 2", "Regular", "15", "17.5", "Semibold" ] ] } ] }, { "heading": "AX2", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "45", "47.5", "Bold" ], [ "Title 1", "Regular", "43", "46", "Semibold" ], [ "Title 2", "Regular", "35", "37.5", "Semibold" ], [ "Title 3", "Regular", "25", "27.5", "Semibold" ], [ "Headline", "Semibold", "22", "24.5", "Semibold" ], [ "Body", "Regular", "22", "24.5", "Semibold" ], [ "Caption 1", "Regular", "19", "21.5", "Semibold" ], [ "Caption 2", "Regular", "18", "20.5", "Semibold" ], [ "Footnote 1", "Regular", "17", "19.5", "Semibold" ], [ "Footnote 2", "Regular", "16", "17.5", "Semibold" ] ] } ] }, { "heading": "AX3", "level": 4, "content": [ { "type": "table", "rows": [ [ "Style", "Weight", "Size (points)", "Leading (points)", "Emphasized weight" ], [ "Large Title", "Regular", "46", "48.5", "Bold" ], [ "Title 1", "Regular", "44", "47", "Semibold" ], [ "Title 2", "Regular", "36", "38.5", "Semibold" ], [ "Title 3", "Regular", "26", "28.5", "Semibold" ], [ "Headline", "Semibold", "23", "25.5", "Semibold" ], [ "Body", "Regular", "23", "25.5", "Semibold" ], [ "Caption 1", "Regular", "20", "22.5", "Semibold" ], [ "Caption 2", "Regular", "19", "21.5", "Semibold" ], [ "Footnote 1", "Regular", "18", "20.5", "Semibold" ], [ "Footnote 2", "Regular", "17", "19.5", "Semibold" ] ] } ] }, { "heading": "SF Pro", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+41", "+0.24" ], [ "7", "+34", "+0.23" ], [ "8", "+26", "+0.21" ], [ "9", "+19", "+0.17" ], [ "10", "+12", "+0.12" ], [ "11", "+6", "+0.06" ], [ "12", "0", "0.0" ], [ "13", "-6", "-0.08" ], [ "14", "-11", "-0.15" ], [ "15", "-16", "-0.23" ], [ "16", "-20", "-0.31" ], [ "17", "-26", "-0.43" ], [ "18", "-25", "-0.44" ], [ "19", "-24", "-0.45" ], [ "20", "-23", "-0.45" ], [ "21", "-18", "-0.36" ], [ "22", "-12", "-0.26" ], [ "23", "-4", "-0.10" ], [ "24", "+3", "+0.07" ], [ "25", "+6", "+0.15" ], [ "26", "+8", "+0.22" ], [ "27", "+11", "+0.29" ], [ "28", "+14", "+0.38" ], [ "29", "+14", "+0.40" ], [ "30", "+14", "+0.40" ], [ "31", "+13", "+0.39" ], [ "32", "+13", "+0.41" ], [ "33", "+12", "+0.40" ], [ "34", "+12", "+0.40" ], [ "35", "+11", "+0.38" ], [ "36", "+10", "+0.37" ], [ "37", "+10", "+0.36" ], [ "38", "+10", "+0.37" ], [ "39", "+10", "+0.38" ], [ "40", "+10", "+0.37" ], [ "41", "+9", "+0.36" ], [ "42", "+9", "+0.37" ], [ "43", "+9", "+0.38" ], [ "44", "+8", "+0.37" ], [ "45", "+8", "+0.35" ], [ "46", "+8", "+0.36" ], [ "47", "+8", "+0.37" ], [ "48", "+8", "+0.35" ], [ "49", "+7", "+0.33" ], [ "50", "+7", "+0.34" ], [ "51", "+7", "+0.35" ], [ "52", "+6", "+0.33" ], [ "53", "+6", "+0.31" ], [ "54", "+6", "+0.32" ], [ "56", "+6", "+0.30" ], [ "58", "+5", "+0.28" ], [ "60", "+4", "+0.26" ], [ "62", "+4", "+0.24" ], [ "64", "+4", "+0.22" ], [ "66", "+3", "+0.19" ], [ "68", "+2", "+0.17" ], [ "70", "+2", "+0.14" ], [ "72", "+2", "+0.14" ], [ "76", "+1", "+0.07" ], [ "80", "0", "0" ], [ "84", "0", "0" ], [ "88", "0", "0" ], [ "92", "0", "0" ], [ "96", "0", "0" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "SF Pro Rounded", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+87", "+0.51" ], [ "7", "+80", "+0.54" ], [ "8", "+72", "+0.57" ], [ "9", "+65", "+0.57" ], [ "10", "+58", "+0.57" ], [ "11", "+52", "+0.56" ], [ "12", "+46", "+0.54" ], [ "13", "+40", "+0.51" ], [ "14", "+35", "+0.48" ], [ "15", "+30", "+0.44" ], [ "16", "+26", "+0.41" ], [ "17", "+22", "+0.37" ], [ "18", "+21", "+0.37" ], [ "19", "+20", "+0.37" ], [ "20", "+18", "+0.36" ], [ "21", "+17", "+0.35" ], [ "22", "+16", "+0.34" ], [ "23", "+16", "+0.35" ], [ "24", "+15", "+0.35" ], [ "25", "+14", "+0.35" ], [ "26", "+14", "+0.36" ], [ "27", "+14", "+0.36" ], [ "28", "+13", "+0.36" ], [ "29", "+13", "+0.37" ], [ "30", "+12", "+0.37" ], [ "31", "+12", "+0.36" ], [ "32", "+12", "+0.38" ], [ "33", "+12", "+0.39" ], [ "34", "+12", "+0.38" ], [ "35", "+11", "+0.38" ], [ "36", "+11", "+0.39" ], [ "37", "+10", "+0.38" ], [ "38", "+10", "+0.39" ], [ "39", "+10", "+0.38" ], [ "40", "+10", "+0.39" ], [ "41", "+10", "+0.38" ], [ "42", "+10", "+0.39" ], [ "43", "+9", "+0.38" ], [ "44", "+8", "+0.37" ], [ "45", "+8", "+0.37" ], [ "46", "+8", "+0.36" ], [ "47", "+8", "+0.37" ], [ "48", "+8", "+0.35" ], [ "49", "+8", "+0.36" ], [ "50", "+7", "+0.34" ], [ "51", "+6", "+0.32" ], [ "52", "+6", "+0.33" ], [ "53", "+6", "+0.31" ], [ "54", "+6", "+0.32" ], [ "56", "+6", "+0.30" ], [ "58", "+4", "+0.25" ], [ "60", "+4", "+0.23" ], [ "62", "+4", "+0.21" ], [ "64", "+3", "+0.19" ], [ "66", "+2", "+0.16" ], [ "68", "+2", "+0.13" ], [ "70", "+2", "+0.14" ], [ "72", "+2", "+0.11" ], [ "76", "+1", "+0.07" ], [ "80", "0", "0.00" ], [ "84", "0", "0.00" ], [ "88", "0", "0.00" ], [ "92", "0", "0.00" ], [ "96", "0", "0.00" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "New York", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+40", "+0.23" ], [ "7", "+32", "+0.22" ], [ "8", "+25", "+0.20" ], [ "9", "+20", "+0.18" ], [ "10", "+16", "+0.15" ], [ "11", "+11", "+.12" ], [ "12", "+6", "+0.07" ], [ "13", "+4", "+0.05" ], [ "14", "+2", "+0.03" ], [ "15", "+0", "+0.00" ], [ "16", "-2", "-0.03" ], [ "17", "-4", "-0.07" ], [ "18", "-6", "-0.11" ], [ "19", "-8", "-0.15" ], [ "20", "-10", "-0.20" ], [ "21", "-10", "-0.21" ], [ "22", "-10", "-0.23" ], [ "23", "-11", "-0.25" ], [ "24", "-11", "-0.26" ], [ "25", "-11", "-0.27" ], [ "26", "-12", "-0.29" ], [ "27", "-12", "-0.32" ], [ "28", "-12", "-0.33" ], [ "29", "-12", "-0.34" ], [ "30", "-12", "-0.37" ], [ "31", "-13", "-0.39" ], [ "32", "-13", "-0.41" ], [ "33", "-13", "-0.42" ], [ "34", "-14", "-0.45" ], [ "35", "-14", "-0.48" ], [ "36", "-14", "-0.49" ], [ "38", "-14", "-0.52" ], [ "40", "-14", "-0.55" ], [ "42", "-14", "-0.57" ], [ "44", "-14", "-0.62" ], [ "46", "-14", "-0.65" ], [ "48", "-14", "-0.68" ], [ "50", "-14", "-0.71" ], [ "52", "-14", "-0.74" ], [ "54", "-15", "-0.79" ], [ "58", "-15", "-0.85" ], [ "62", "-15", "-0.91" ], [ "66", "-15", "-0.97" ], [ "70", "-16", "-1.06" ], [ "72", "-16", "-1.09" ], [ "80", "-16", "-1.21" ], [ "88", "-16", "-1.33" ], [ "96", "-16", "-1.50" ], [ "100", "-16", "-1.56" ], [ "120", "-16", "-1.88" ], [ "140", "-16", "-2.26" ], [ "160", "-16", "-2.58" ], [ "180", "-17", "-2.99" ], [ "200", "-17", "-3.32" ], [ "220", "-18", "-3.76" ], [ "240", "-18", "-4.22" ], [ "260", "-18", "-4.57" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "macOS tracking values", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+41", "+0.24" ], [ "7", "+34", "+0.23" ], [ "8", "+26", "+0.21" ], [ "9", "+19", "+0.17" ], [ "10", "+12", "+0.12" ], [ "11", "+6", "+0.06" ], [ "12", "0", "0.0" ], [ "13", "-6", "-0.08" ], [ "14", "-11", "-0.15" ], [ "15", "-16", "-0.23" ], [ "16", "-20", "-0.31" ], [ "17", "-26", "-0.43" ], [ "18", "-25", "-0.44" ], [ "19", "-24", "-0.45" ], [ "20", "-23", "-0.45" ], [ "21", "-18", "-0.36" ], [ "22", "-12", "-0.26" ], [ "23", "-4", "-0.10" ], [ "24", "+3", "+0.07" ], [ "25", "+6", "+0.15" ], [ "26", "+8", "+0.22" ], [ "27", "+11", "+0.29" ], [ "28", "+14", "+0.38" ], [ "29", "+14", "+0.40" ], [ "30", "+14", "+0.40" ], [ "31", "+13", "+0.39" ], [ "32", "+13", "+0.41" ], [ "33", "+12", "+0.40" ], [ "34", "+12", "+0.40" ], [ "35", "+11", "+0.38" ], [ "36", "+10", "+0.37" ], [ "37", "+10", "+0.36" ], [ "38", "+10", "+0.37" ], [ "39", "+10", "+0.38" ], [ "40", "+10", "+0.37" ], [ "41", "+9", "+0.36" ], [ "42", "+9", "+0.37" ], [ "43", "+9", "+0.38" ], [ "44", "+8", "+0.37" ], [ "45", "+8", "+0.35" ], [ "46", "+8", "+0.36" ], [ "47", "+8", "+0.37" ], [ "48", "+8", "+0.35" ], [ "49", "+7", "+0.33" ], [ "50", "+7", "+0.34" ], [ "51", "+7", "+0.35" ], [ "52", "+6", "+0.31" ], [ "53", "+6", "+0.33" ], [ "54", "+6", "+0.32" ], [ "56", "+6", "+0.30" ], [ "58", "+5", "+0.28" ], [ "60", "+4", "+0.26" ], [ "62", "+4", "+0.24" ], [ "64", "+4", "+0.22" ], [ "66", "+3", "+0.19" ], [ "68", "+2", "+0.17" ], [ "70", "+2", "+0.14" ], [ "72", "+2", "+0.14" ], [ "76", "+1", "+0.07" ], [ "80", "0", "0" ], [ "84", "0", "0" ], [ "88", "0", "0" ], [ "92", "0", "0" ], [ "96", "0", "0" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "tvOS tracking values", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+41", "+0.24" ], [ "7", "+34", "+0.23" ], [ "8", "+26", "+0.21" ], [ "9", "+19", "+0.17" ], [ "10", "+12", "+0.12" ], [ "11", "+6", "+0.06" ], [ "12", "0", "0.0" ], [ "13", "-6", "-0.08" ], [ "14", "-11", "-0.15" ], [ "15", "-16", "-0.23" ], [ "16", "-20", "-0.31" ], [ "17", "-26", "-0.43" ], [ "18", "-25", "-0.44" ], [ "19", "-24", "-0.45" ], [ "20", "-23", "-0.45" ], [ "21", "-18", "-0.36" ], [ "22", "-12", "-0.26" ], [ "23", "-4", "-0.10" ], [ "24", "+3", "+0.07" ], [ "25", "+6", "+0.15" ], [ "26", "+8", "+0.22" ], [ "27", "+11", "+0.29" ], [ "28", "+14", "+0.38" ], [ "29", "+14", "+0.40" ], [ "30", "+14", "+0.40" ], [ "31", "+13", "+0.39" ], [ "32", "+13", "+0.41" ], [ "33", "+12", "+0.40" ], [ "34", "+12", "+0.40" ], [ "35", "+11", "+0.38" ], [ "36", "+10", "+0.37" ], [ "37", "+10", "+0.36" ], [ "38", "+10", "+0.37" ], [ "39", "+10", "+0.38" ], [ "40", "+10", "+0.37" ], [ "41", "+9", "+0.36" ], [ "42", "+9", "+0.37" ], [ "43", "+9", "+0.38" ], [ "44", "+8", "+0.37" ], [ "45", "+8", "+0.35" ], [ "46", "+8", "+0.36" ], [ "47", "+8", "+0.37" ], [ "48", "+8", "+0.35" ], [ "49", "+7", "+0.33" ], [ "50", "+7", "+0.34" ], [ "51", "+7", "+0.35" ], [ "52", "+6", "+0.31" ], [ "53", "+6", "+0.33" ], [ "54", "+6", "+0.32" ], [ "56", "+6", "+0.30" ], [ "58", "+5", "+0.28" ], [ "60", "+4", "+0.26" ], [ "62", "+4", "+0.24" ], [ "64", "+4", "+0.22" ], [ "66", "+3", "+0.19" ], [ "68", "+2", "+0.17" ], [ "70", "+2", "+0.14" ], [ "72", "+2", "+0.14" ], [ "76", "+1", "+0.07" ], [ "80", "0", "0" ], [ "84", "0", "0" ], [ "88", "0", "0" ], [ "92", "0", "0" ], [ "96", "0", "0" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x and 216 ppi for @3x designs." } ] }, { "heading": "SF Compact", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+50", "+0.29" ], [ "7", "+30", "+0.21" ], [ "8", "+30", "+0.23" ], [ "9", "+30", "+0.26" ], [ "10", "+30", "+0.29" ], [ "11", "+24", "+0.26" ], [ "12", "+20", "+0.23" ], [ "13", "+16", "+0.20" ], [ "14", "+14", "+0.19" ], [ "15", "+4", "+0.06" ], [ "16", "0", "0.00" ], [ "17", "-4", "-0.07" ], [ "18", "-8", "-0.14" ], [ "19", "-12", "-0.22" ], [ "20", "0", "0.00" ], [ "21", "-2", "-0.04" ], [ "22", "-4", "-0.09" ], [ "23", "-6", "-0.13" ], [ "24", "-8", "-0.19" ], [ "25", "-10", "-0.24" ], [ "26", "-11", "-0.28" ], [ "27", "-12", "-0.30" ], [ "28", "-12", "-0.34" ], [ "29", "-14", "-0.38" ], [ "30", "-14", "-0.42" ], [ "31", "-15", "-0.45" ], [ "32", "-16", "-0.50" ], [ "33", "-17", "-0.55" ], [ "34", "-18", "-0.60" ], [ "35", "-18", "-0.63" ], [ "36", "-20", "-0.69" ], [ "37", "-20", "-0.72" ], [ "38", "-20", "-0.74" ], [ "39", "-20", "-0.76" ], [ "40", "-20", "-0.78" ], [ "41", "-20", "-0.80" ], [ "42", "-20", "-0.82" ], [ "43", "-20", "-0.84" ], [ "44", "-20", "-0.86" ], [ "45", "-20", "-0.88" ], [ "46", "-20", "-0.92" ], [ "47", "-20", "-0.94" ], [ "48", "-20", "-0.96" ], [ "49", "-21", "-1.00" ], [ "50", "-21", "-1.03" ], [ "51", "-21", "-1.05" ], [ "52", "-21", "-1.07" ], [ "53", "-22", "-1.11" ], [ "54", "-22", "-1.13" ], [ "56", "-22", "-1.20" ], [ "58", "-22", "-1.25" ], [ "60", "-22", "-1.32" ], [ "62", "-22", "-1.36" ], [ "64", "-23", "-1.44" ], [ "66", "-24", "-1.51" ], [ "68", "-24", "-1.56" ], [ "70", "-24", "-1.64" ], [ "72", "-24", "-1.69" ], [ "76", "-25", "-1.86" ], [ "80", "-26", "-1.99" ], [ "84", "-26", "-2.13" ], [ "88", "-26", "-2.28" ], [ "92", "-28", "-2.47" ], [ "96", "-28", "-2.62" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x designs." } ] }, { "heading": "SF Compact Rounded", "level": 4, "content": [ { "type": "table", "rows": [ [ "Size (points)", "Tracking (1/1000 em)", "Tracking (points)" ], [ "6", "+28", "+0.16" ], [ "7", "+26", "+0.18" ], [ "8", "+24", "+0.19" ], [ "9", "+22", "+0.19" ], [ "10", "+20", "+0.20" ], [ "11", "+18", "+0.19" ], [ "12", "+16", "+0.19" ], [ "13", "+14", "+0.18" ], [ "14", "+12", "+0.16" ], [ "15", "+10", "+0.15" ], [ "16", "+8", "+0.12" ], [ "17", "+6", "+0.10" ], [ "18", "+4", "+0.07" ], [ "19", "+2", "+0.04" ], [ "20", "0", "0.00" ], [ "21", "-2", "-0.04" ], [ "22", "-4", "-0.09" ], [ "23", "-6", "-0.13" ], [ "24", "-8", "-0.19" ], [ "25", "-10", "-0.24" ], [ "26", "-11", "-0.28" ], [ "27", "-12", "-0.30" ], [ "28", "-12", "-0.34" ], [ "29", "-14", "-0.38" ], [ "30", "-14", "-0.42" ], [ "31", "-15", "-0.45" ], [ "32", "-16", "-0.50" ], [ "33", "-17", "-0.55" ], [ "34", "-18", "-0.60" ], [ "35", "-18", "-0.63" ], [ "36", "-20", "-0.69" ], [ "37", "-20", "-0.72" ], [ "38", "-20", "-0.74" ], [ "39", "-20", "-0.76" ], [ "40", "-20", "-0.78" ], [ "41", "-20", "-0.80" ], [ "42", "-20", "-0.82" ], [ "43", "-20", "-0.84" ], [ "44", "-20", "-0.86" ], [ "45", "-20", "-0.88" ], [ "46", "-20", "-0.92" ], [ "47", "-20", "-0.94" ], [ "48", "-20", "-0.96" ], [ "49", "-21", "-1.00" ], [ "50", "-21", "-1.03" ], [ "51", "-21", "-1.05" ], [ "52", "-21", "-1.07" ], [ "53", "-22", "-1.11" ], [ "54", "-22", "-1.13" ], [ "56", "-22", "-1.20" ], [ "58", "-22", "-1.25" ], [ "60", "-22", "-1.32" ], [ "62", "-22", "-1.36" ], [ "64", "-23", "-1.44" ], [ "66", "-24", "-1.51" ], [ "68", "-24", "-1.56" ], [ "70", "-24", "-1.64" ], [ "72", "-24", "-1.69" ], [ "76", "-25", "-1.86" ], [ "80", "-26", "-1.99" ], [ "84", "-26", "-2.13" ], [ "88", "-26", "-2.28" ], [ "92", "-28", "-2.47" ], [ "96", "-28", "-2.62" ] ] }, { "type": "paragraph", "text": "Not all apps express tracking values as 1/1000 em. Point size based on image resolution of 144 ppi for @2x designs." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Fonts for Apple platforms" }, { "type": "paragraph", "text": "SF Symbols" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Text input and output — SwiftUI" }, { "type": "paragraph", "text": "Text display and fonts — UIKit" }, { "type": "paragraph", "text": "Fonts — AppKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Added emphasized weights to the Dynamic Type style specifications for each platform." ], [ "March 7, 2025", "Expanded guidance for Dynamic Type." ], [ "June 10, 2024", "Added guidance for using Apple’s Unity plug-ins to support Dynamic Type in a Unity-based game and enhanced guidance on billboarding in a visionOS app or game." ], [ "September 12, 2023", "Added artwork illustrating system font weights, and clarified tvOS specification table descriptions." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ] ] } ] } ], "platforms": [], "related": [ { "title": "Ensuring legibility", "url": "/design/human-interface-guidelines/typography#Ensuring-legibility" }, { "title": "Conveying hierarchy", "url": "/design/human-interface-guidelines/typography#Conveying-hierarchy" }, { "title": "Using system fonts", "url": "/design/human-interface-guidelines/typography#Using-system-fonts" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Supporting Dynamic Type", "url": "/design/human-interface-guidelines/typography#Supporting-Dynamic-Type" }, { "title": "Tracking values", "url": "/design/human-interface-guidelines/typography#Tracking-values" }, { "title": "Using custom fonts", "url": "/design/human-interface-guidelines/typography#Using-custom-fonts" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/typography#Specifications" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/typography#Platform-considerations" }, { "title": "iOS, iPadOS", "url": "/design/human-interface-guidelines/typography#iOS-iPadOS" }, { "title": "macOS", "url": "/design/human-interface-guidelines/typography#macOS" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/typography#tvOS" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/typography#visionOS" }, { "title": "Materials > visionOS", "url": "/design/human-interface-guidelines/materials#visionOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/typography#watchOS" }, { "title": "iOS, iPadOS Dynamic Type sizes", "url": "/design/human-interface-guidelines/typography#iOS-iPadOS-Dynamic-Type-sizes" }, { "title": "xSmall", "url": "/design/human-interface-guidelines/typography#xSmall" }, { "title": "Small", "url": "/design/human-interface-guidelines/typography#Small" }, { "title": "Medium", "url": "/design/human-interface-guidelines/typography#Medium" }, { "title": "Large (default)", "url": "/design/human-interface-guidelines/typography#Large-default" }, { "title": "xLarge", "url": "/design/human-interface-guidelines/typography#xLarge" }, { "title": "xxLarge", "url": "/design/human-interface-guidelines/typography#xxLarge" }, { "title": "xxxLarge", "url": "/design/human-interface-guidelines/typography#xxxLarge" }, { "title": "iOS, iPadOS larger accessibility type sizes", "url": "/design/human-interface-guidelines/typography#iOS-iPadOS-larger-accessibility-type-sizes" }, { "title": "AX1", "url": "/design/human-interface-guidelines/typography#AX1" }, { "title": "AX2", "url": "/design/human-interface-guidelines/typography#AX2" }, { "title": "AX3", "url": "/design/human-interface-guidelines/typography#AX3" }, { "title": "AX4", "url": "/design/human-interface-guidelines/typography#AX4" }, { "title": "AX5", "url": "/design/human-interface-guidelines/typography#AX5" }, { "title": "macOS built-in text styles", "url": "/design/human-interface-guidelines/typography#macOS-built-in-text-styles" }, { "title": "tvOS built-in text styles", "url": "/design/human-interface-guidelines/typography#tvOS-built-in-text-styles" }, { "title": "watchOS Dynamic Type sizes", "url": "/design/human-interface-guidelines/typography#watchOS-Dynamic-Type-sizes" }, { "title": "Small (default 38mm)", "url": "/design/human-interface-guidelines/typography#Small-default-38mm" }, { "title": "Large (default 40mm/41mm/42mm)", "url": "/design/human-interface-guidelines/typography#Large-default-40mm41mm42mm" }, { "title": "xLarge (default 44mm/45mm/49mm)", "url": "/design/human-interface-guidelines/typography#xLarge-default-44mm45mm49mm" }, { "title": "watchOS larger accessibility type sizes", "url": "/design/human-interface-guidelines/typography#watchOS-larger-accessibility-type-sizes" }, { "title": "iOS, iPadOS, visionOS tracking values", "url": "/design/human-interface-guidelines/typography#iOS-iPadOS-visionOS-tracking-values" }, { "title": "SF Pro", "url": "/design/human-interface-guidelines/typography#SF-Pro" }, { "title": "SF Pro Rounded", "url": "/design/human-interface-guidelines/typography#SF-Pro-Rounded" }, { "title": "New York", "url": "/design/human-interface-guidelines/typography#New-York" }, { "title": "macOS tracking values", "url": "/design/human-interface-guidelines/typography#macOS-tracking-values" }, { "title": "tvOS tracking values", "url": "/design/human-interface-guidelines/typography#tvOS-tracking-values" }, { "title": "watchOS tracking values", "url": "/design/human-interface-guidelines/typography#watchOS-tracking-values" }, { "title": "SF Compact", "url": "/design/human-interface-guidelines/typography#SF-Compact" }, { "title": "SF Compact Rounded", "url": "/design/human-interface-guidelines/typography#SF-Compact-Rounded" }, { "title": "Resources", "url": "/design/human-interface-guidelines/typography#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/typography#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/typography#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/typography#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/typography#Change-log" } ], "image_count": 0 }, { "title": "Writing", "url": "https://developer.apple.com/design/human-interface-guidelines/writing", "category": "foundations", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Whether you’re building an onboarding experience, writing an alert, or describing an image for accessibility, designing through the lens of language will help people get the most from your app or game." } ] }, { "heading": "Getting started", "level": 2, "content": [ { "type": "paragraph", "text": "Determine your app’s voice. Think about who you’re talking to, so you can figure out the type of vocabulary you’ll use. What types of words are familiar to people using your app? How do you want people to feel? The words for a banking app might convey trust and stability, for example, while the words in a game might convey excitement and fun. Create a list of common terms, and reference that list to keep your language consistent. Consistent language, along with a voice that reflects your app’s values, helps everything feel more cohesive." }, { "type": "paragraph", "text": "Match your tone to the context. Once you’ve established your app’s voice, vary your tone based on the situation. Consider what people are doing while they’re using your app — both in the physical world and within the app itself. Are they exercising and reached a goal? Or are they trying to make a payment and received an error? Situational factors affect both what you say and how you display the text on the screen." }, { "type": "paragraph", "text": "Compare the tone of these two examples from Apple Watch. In the first, the tone is straightforward and direct, reflecting the seriousness of the situation. In the second, the tone is light and congratulatory." }, { "type": "paragraph", "text": "Be clear. Choose words that are easily understood and convey the right thing. Check each word to be sure it needs to be there. If you can use fewer words, do so. When in doubt, read your writing out loud." }, { "type": "paragraph", "text": "Write for everyone. For your app to be useful for as many people as possible, it needs to speak to as many people as possible. Choose simple, plain language and write with accessibility and localization in mind, avoiding jargon and gendered terminology. For guidance, see Writing inclusively and VoiceOver; for developer guidance, see Localization." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Consider each screen’s purpose. Pay attention to the order of elements on a screen, and put the most important information first. Format your text to make it easy to read. If you’re trying to convey more than one idea, consider breaking up the text onto multiple screens, and think about the flow of information across those screens." }, { "type": "paragraph", "text": "Be action oriented. Active voice and clear labels help people navigate through your app from one step to the next, or from one screen to another. When labeling buttons and links, it’s almost always best to use a verb. Prioritize clarity and avoid the temptation to be too cute or clever with your labels. For example, just saying “Send” often works better than “Let’s do it!” For links, avoid using “Click here” in favor of more descriptive words or phrases, such as “Learn more about UX Writing.” This is especially important for people using screen readers to access your app." }, { "type": "paragraph", "text": "Build language patterns. Consistency builds familiarity, helping your app feel cohesive, intuitive, and thoughtfully designed. It also makes writing for your app easier, as you can return to these patterns again and again." }, { "type": "paragraph", "text": "Adopt capitalization rules that align with your app’s style, then apply them consistently. While certain components, like button labels, have specific guidelines, how you format text reflects your app’s voice. Title case is generally considered formal, while sentence case is more casual. Choose a style for each UI element type and use it consistently throughout your app — for example, title case for all alerts or sentence case for all headlines." }, { "type": "paragraph", "text": "Give clear guidance and use consistent language throughout processes with multiple steps. If your app has a flow that spans multiple screens, decide how you want to label the actions that take people from one step to the next. Begin with language like “Get Started” to indicate you’re starting a flow. You can use the button label to hint at the next step, or use terms like “Continue” or “Next,” but be consistent with what you choose. Make it clear when a flow is complete by using language like “Done.”" }, { "type": "paragraph", "text": "Use possessive pronouns sparingly. Possessive pronouns like my and your are often unnecessary to establish context. For example, “Favorites” conveys the same message as “Your Favorites,” and is more succinct. If you do use possessive pronouns, use them consistently throughout your app, and try not to switch perspectives. Avoid using we altogether because it may be unclear who the “we” in question refers to. This is particularly problematic in error messages like “We’re having trouble loading this content.” Something like “Unable to load content” is much clearer." }, { "type": "paragraph", "text": "Write for how people use each device. People may use your app on several types of devices. While your language needs to be consistent across them, think about where it would be helpful to adjust your text to make it suitable for different devices. Make sure you describe gestures correctly on each device — for example, not saying “click” for a touch device like iPhone or iPad where you mean “tap.”" }, { "type": "paragraph", "text": "Where and how people use a device, its screen size, and its location all affect how you write for your app. iPhone and Apple Watch, for example, offer opportunities for personalization, but their small screens require brevity. TVs, on the other hand, are often in common living spaces, and several people are likely to see anything on the screen, so consider who you’re addressing. Bigger screens also require brevity, as the text must be large for people to see it from a distance." }, { "type": "paragraph", "text": "Provide clear next steps on any blank screens. An empty state, like a completed to-do list or bookmarks folder with nothing in it, can provide a good opportunity to make people feel welcome and educate them about your app. Empty states can also showcase your app’s voice, but make sure that the content is useful and fits the context. An empty screen can be daunting if it isn’t obvious what to do next, so guide people on actions they can take, and give them a button or link to do so if possible. Remember that empty states are usually temporary, so don’t show crucial information that could then disappear." }, { "type": "paragraph", "text": "Write clear error messages. It’s always best to help people avoid errors. When an error message is necessary, display it as close to the problem as possible, avoid blame, and be clear about what someone can do to fix it. For example, “That password is too short” isn’t as helpful as “Choose a password with at least 8 characters.” Remember that errors can be frustrating. Interjections like “oops!” or “uh-oh” are typically unnecessary and can sound insincere. If you find that language alone can’t address an error that’s likely to affect many people, use that as an opportunity to rethink the interaction." }, { "type": "paragraph", "text": "Choose the right delivery method. There are many ways to get people’s attention, whether or not they are actively using your app. When there’s something you want to communicate, consider the urgency and importance of the message. Think about the context in which someone might see the message, whether it requires immediate action, and how much supporting information someone might need. Choose the correct delivery method, and use a tone appropriate for the situation. For guidance, see Notifications, Alerts, and Action sheets." }, { "type": "paragraph", "text": "Keep settings labels clear and simple. Help people easily find the settings they need by labeling them as practically as possible. If the setting label isn’t enough, add an explanation. Describe what it does when turned on, and people can infer the opposite. In the Handwashing Timer setting for Apple Watch, for example, the description explains that a timer can start when you’re washing your hands. It isn’t necessary to tell you that a timer won’t start when this setting is off." }, { "type": "paragraph", "text": "If you need to direct someone to a setting, provide a direct link or button, rather than trying to describe its location. For guidance, see Settings." }, { "type": "paragraph", "text": "Show hints in text fields. If your app allows people to enter their own text, like account or contact information, label all fields clearly, and use hint or placeholder text so people know how to format the information. You can give an example in hint text, like “name@example.com,” or describe the information, such as “Your name.” Show errors right next to the field, and instruct people how to enter the information correctly, rather than scolding them for not following the rules. “Use only letters for your name” is better than “Don’t use numbers or symbols.” Avoid robotic error messages with no helpful information, like “Invalid name.” For guidance, see Text fields." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Style Guide" }, { "type": "paragraph", "text": "Writing inclusively" }, { "type": "paragraph", "text": "Inclusion" }, { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Color" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Clarified guidance on language patterns, and added guidance for possessive pronouns." ], [ "February 27, 2023", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Getting started", "url": "/design/human-interface-guidelines/writing#Getting-started" }, { "title": "VoiceOver", "url": "/design/human-interface-guidelines/voiceover" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/writing#Best-practices" }, { "title": "button labels", "url": "/design/human-interface-guidelines/buttons#Content" }, { "title": "Notifications", "url": "/design/human-interface-guidelines/notifications" }, { "title": "Alerts", "url": "/design/human-interface-guidelines/alerts" }, { "title": "Action sheets", "url": "/design/human-interface-guidelines/action-sheets" }, { "title": "Settings", "url": "/design/human-interface-guidelines/settings" }, { "title": "Text fields", "url": "/design/human-interface-guidelines/text-fields" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/writing#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/writing#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/writing#Related" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Videos", "url": "/design/human-interface-guidelines/writing#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/writing#Change-log" } ], "image_count": 0 } ] }