Hig Foundations

Apple HIG: Design Foundations

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Prioritize content over chrome. Reduce visual clutter. Use system-provided materials and subtle separators rather than heavy borders and backgrounds.

2. Build in accessibility from the start. Design for VoiceOver, Dynamic Type, Reduce Motion, Increase Contrast, and Switch Control from day one. Every interactive element needs an accessible label.

3. Use system colors and materials. System colors adapt to light/dark mode, increased contrast, and vibrancy. Prefer semantic colors (label, secondaryLabel, systemBackground) over hard-coded values.

4. Use platform fonts and icons. SF Pro, SF Compact, SF Mono by default. New York for serif. Follow the type hierarchy at recommended sizes. Use SF Symbols for iconography.

5. Match platform conventions. Align look and behavior with system standards. Provide direct, responsive manipulation and clear feedback for every action.

6. Respect privacy. Request permissions only when needed, explain why clearly, provide value before asking for data. Design for minimal data collection.

7. Support internationalization. Accommodate text expansion, right-to-left scripts, and varying date/number formats. Use Auto Layout for dynamic content sizing.

8. Use motion purposefully. Animation should communicate meaning and spatial relationships. Honor Reduce Motion by providing crossfade alternatives.

Reference Index

Applying Foundations Together

Consider how principles interact:

1. Color + Dark Mode + Accessibility -- Custom palettes must work in both modes while maintaining WCAG contrast ratios. Start with system semantic colors.

2. Typography + Accessibility + Layout -- Dynamic Type must scale without breaking layouts. Use text styles and Auto Layout for the full range of type sizes.

3. Icons + Branding + SF Symbols -- Custom icons should match SF Symbols weight and optical sizing. Brand elements should integrate without overriding system conventions.

4. Motion + Accessibility + Feedback -- Every animation must have a Reduce Motion alternative. Motion should reinforce spatial relationships, not decorate.

5. Privacy + Writing + Onboarding -- Permission requests need clear, specific usage descriptions. Time them to when the user will understand the benefit.

Output Format

1. Cite the specific HIG foundation with file and section. 2. Note platform differences for the user's target platforms. 3. Provide concrete code patterns (SwiftUI/UIKit/AppKit). 4. Explain accessibility impact (contrast ratios, Dynamic Type scaling, VoiceOver behavior).

Questions to Ask

1. Which platforms are you targeting? 2. Do you have existing brand guidelines? 3. What accessibility level are you targeting? (WCAG AA, AAA, Apple baseline?) 4. System colors or custom?

Related Skills

• hig-platforms -- How foundations apply per platform (e.g., type scale differences on watchOS vs macOS)
• hig-patterns -- Interaction patterns where foundations like writing and accessibility are critical
• hig-components-layout -- Structural components implementing layout principles
• hig-components-content -- Content display using color, typography, and images

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/accessibility.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Accessibility

• 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.

Vision

Support larger text sizes.

Use recommended defaults for custom type sizes.

Bear in mind that font weight can also impact how easy text is to read.

Strive to meet color contrast minimum standards.

Prefer system-defined colors.

Convey information with more than color alone.

Describe your app’s interface and content for VoiceOver.

Hearing

Support text-based ways to enjoy audio and video.

• 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.

Use haptics in addition to audio cues.

Augment audio cues with visual cues.

Mobility

Offer sufficiently sized controls.

Consider spacing between controls as important as size.

Support simple gestures for common interactions.

Offer alternatives to gestures.

Let people use Voice Control to give guidance and enter information verbally.

Integrate with Siri and Shortcuts to let people perform tasks using voice alone.

Support mobility-related assistive technologies.

Speech

Let people use the keyboard alone to navigate and interact with your app.

Support Switch Control.

Cognitive

Keep actions simple and intuitive.

Minimize use of time-boxed interface elements.

Consider offering difficulty accommodations in games.

Let people control audio and video playback.

Allow people to opt out of flashing lights in video playback.

Be cautious with fast-moving and blinking animations.

• 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

Optimize your app’s UI for Assistive Access.

• 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.

Platform considerations

visionOS

• Pointer Control (hand)
• Pointer Control (head)
• Zoom

Prioritize comfort.

• 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.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/accessibility

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/app-icons.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

App icons

Layer design

Prefer clearly defined edges in foreground layers.

Vary opacity in foreground layers to increase the sense of depth and liveliness.

Design a background that both stands out and emphasizes foreground content.

Prefer vector graphics when bringing layers into Icon Composer.

Icon shape

• iOS, iPadOS, macOS
• tvOS
• visionOS, watchOS

Produce appropriately shaped, unmasked layers.

Keep primary content centered to avoid truncation when the system adjusts corners or applies masking.

Design

Provide a visually consistent icon design across all the platforms your app supports.

Consider basing your icon design around filled, overlapping shapes.

Include text only when it’s essential to your experience or brand.

Prefer illustrations to photos and avoid replicating UI components.

Don’t use replicas of Apple hardware products.

Visual effects

Let the system handle blurring and other visual effects.

Create layer groupings to apply effects to multiple layers at once.

Appearances

Keep your icon’s features consistent across appearances.

Design dark and tinted icons that feel at home beside system app icons and widgets.

Use your light app icon as the basis for your dark icon.

Consider offering alternate app icons.

Platform considerations

tvOS

Include a safe zone to ensure the system doesn’t crop your content.

visionOS

Avoid adding a shape that’s intended to look like a hole or concave area to the background layer.

watchOS

Avoid using black for your icon’s background.

Specifications

• sRGB (color)

• Gray Gamma 2.2 (grayscale)

• Display P3 (wide-gamut color in iOS, iPadOS, macOS, tvOS, and watchOS only)

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/app-icons

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/branding.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Branding

Best practices

Use your brand’s unique voice and tone in all the written communication you display.

Consider choosing an accent color.

Consider using a custom font.

Ensure branding always defers to content.

Help people feel comfortable by using standard patterns consistently.

Resist the temptation to display your logo throughout your app or game unless it’s essential for providing context.

Avoid using a launch screen as a branding opportunity.

Follow Apple’s trademark guidelines.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/branding

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/color.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Color

Best practices

Avoid using the same color to mean different things.

Make sure all your app’s colors work well in light, dark, and increased contrast contexts.

Test your app’s color scheme under a variety of lighting conditions.

Test your app on different devices.

Consider how artwork and translucency affect nearby colors.

If your app lets people choose colors, prefer system-provided color controls where available.

Inclusive color

Avoid relying solely on color to differentiate between objects, indicate interactivity, or communicate essential information.

Avoid using colors that make it hard to perceive content in your app.

Consider how the colors you use might be perceived in other countries and cultures.

System colors

Avoid hard-coding system color values in your app.

Avoid redefining the semantic meanings of dynamic system colors.

Liquid Glass color

Apply color sparingly to the Liquid Glass material, and to symbols or text on the material.

Avoid using similar colors in control labels if your app has a colorful background.

Be aware of the placement of color in the content layer.

Color management

Apply color profiles to your images.

Use wide color to enhance the visual experience on compatible displays.

Provide color space–specific image and color variations if necessary.

Platform considerations

iOS, iPadOS

• Primary for the overall view

• Secondary for grouping content or elements within the overall view

• Tertiary for grouping content or elements within secondary elements

tvOS

Consider choosing a limited color palette that coordinates with your app logo.

Avoid using only color to indicate focus.

visionOS

Use color sparingly, especially on glass.

Prefer using color in bold text and large areas.

In a fully immersive experience, help people maintain visual comfort by keeping brightness levels balanced.

watchOS

Use background color to support existing content or supply additional information.

Recognize that people might prefer graphic complications to use tinted mode instead of full color.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/color

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/dark-mode.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Dark Mode

Best practices

Avoid offering an app-specific appearance setting.

Ensure that your app looks good in both appearance modes.

Test your content to make sure that it remains comfortably legible in both appearance modes.

In rare cases, consider using only a dark appearance in the interface.

Dark Mode colors

Embrace colors that adapt to the current appearance.

Aim for sufficient color contrast in all appearances.

Soften the color of white backgrounds.

Icons and images

Use SF Symbols wherever possible.

Design separate interface icons for the light and dark appearances if necessary.

Make sure full-color images and icons look good in both appearances.

Text

Use the system-provided label colors for labels.

Use system views to draw text fields and text views.

Platform considerations

iOS, iPadOS

Prefer the system background colors.

macOS

Include some transparency in custom component backgrounds when appropriate.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/dark-mode

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/icons.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Icons

Best practices

Create a recognizable, highly simplified design.

Maintain visual consistency across all interface icons in your app.

In general, match the weights of interface icons and adjacent text.

If necessary, add padding to a custom interface icon to achieve optical alignment.

Provide a selected-state version of an interface icon only if necessary.

Use inclusive images.

Include text in your design only when it’s essential for conveying meaning.

If you create a custom interface icon, use a vector format like PDF or SVG.

Provide alternative text labels for custom interface icons.

Avoid using replicas of Apple hardware products.

Platform considerations

macOS

Document icons

Design simple images that clearly communicate the document type.

Designing a single, expressive image for the background fill can be a great way to help people understand and recognize a document type.

Consider reducing complexity in the small versions of your document icon.

Avoid placing important content in the top-right corner of your background fill.

• 512x512 px @1x, 1024x1024 px @2x

• 256x256 px @1x, 512x512 px @2x

• 128x128 px @1x, 256x256 px @2x

• 32x32 px @1x, 64x64 px @2x

• 16x16 px @1x, 32x32 px @2x

If a familiar object can convey a document’s type or its connection with your app, consider creating a center image that depicts it.

• 256x256 px @1x, 512x512 px @2x

• 128x128 px @1x, 256x256 px @2x

• 32x32 px @1x, 64x64 px @2x

• 16x16 px @1x, 32x32 px @2x

Define a margin that measures about 10% of the image canvas and keep most of the image within it.

Specify a succinct term if it helps people understand your document type.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/icons

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/images.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Images

Resolution

Provide high-resolution assets for all bitmap images in your app, for every device you support.

In general, design images at the lowest resolution and scale them up to create high-resolution assets.

Best practices

Include a color profile with each image.

Always test images on a range of actual devices.

Platform considerations

tvOS

Layered images

Use standard interface elements to display layered images.

Identify logical foreground, middle, and background elements.

Generally, keep text in the foreground.

Keep the background layer opaque.

Keep layering simple and subtle.

Leave a safe zone around the foreground layers of your image.

Always preview layered images.

visionOS

Create a layered app icon.

Prefer vector-based art for 2D images.

If you need to use rasterized images, balance quality with performance as you choose a resolution.

Spatial photos and spatial scenes

Make sure spatial photos render correctly in your app.

Prefer the feathered glass background effect to display text over spatial photos.

Take visual comfort into consideration when you make spatial photos from existing 2D content.

Display spatial photos and spatial scenes in standalone views.

Use spatial scenes in your app for specific moments.

When displaying immersively, prefer minimal UI.

Prefer displaying larger spatial scenes that you center in someone’s field of view.

watchOS

In general, avoid transparency to keep image files small.

Use autoscaling PDFs to let you provide a single asset for all screen sizes.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/images

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/immersive-experiences.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Immersive experiences

Immersion and passthrough

Immersion styles

• 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`.

• Without dimmed passthrough
• With dimmed passthrough

• 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`.

• 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`.

• Full Space (Mixed)
• Full Space (Progressive)
• Full Space (Immersive)

Best practices

Offer multiple ways to use your app or game.

Prefer launching your app or game in the Shared Space or using the`mixed` immersion style.

Reserve immersion for meaningful moments and content.

Help people engage with key moments in your app or game, regardless of the level of immersion.

Prefer subtle tint colors for passthrough.

Promoting comfort

Be mindful of people’s visual comfort.

Choose a style of immersion that supports the movements people might make while they’re in your app or game.

Avoid encouraging people to move while they’re in a progressive or fully immersive experience.

If you use the`mixed` immersion style, avoid obscuring passthrough too much.

Adopt ARKit if you want to blend custom content with someone’s surroundings.

Transitioning between immersive styles

Design smooth, predictable transitions when changing immersion.

Let people choose when to enter or exit a more immersive experience.

Indicate the purpose of an exit control.

Displaying virtual hands

Prefer virtual hands that match familiar characteristics.

Use caution if you create virtual hands that are larger than the viewer’s hands.

If there’s an interruption in hand-tracking data, fade out virtual hands and reveal the viewer’s own hands.

Creating an environment

Minimize distracting content.

Help people distinguish interactive objects in your environment.

Keep animation subtle.

Create an expansive environment, regardless of the place it depicts.

Use Spatial Audio to create atmosphere.

In general, avoid using a flat 360-degree image to create your environment.

Help people feel grounded.

Minimize asset redundancy.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/immersive-experiences

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/inclusion.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Inclusion

Inclusive by design

• 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

Welcoming language

Consider the tone of your copy from different perspectives.

Pay attention to how you refer to people.

Avoid using specialized or technical terms without defining them.

Replace colloquial expressions with plain language.

Consider carefully before including humor.

Being approachable

• 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.

Avoiding stereotypes

• 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?

• What’s your favorite activity?

• What was the name of your first friend?

• What quality describes you best?

Accessibility

• 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.

Avoid images and language that exclude people with disabilities.

Take a people-first approach when writing about people with disabilities.

Prioritize simplicity and perceivability.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/inclusion

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/layout.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Layout

Best practices

Group related items to help people find the information they want.

Make essential information easy to find by giving it sufficient space.

Extend content to fill the screen or window.

Visual hierarchy

Differentiate controls from content.

Place items to convey their relative importance.

Align components with one another to make them easier to scan and to communicate organization and hierarchy.

Take advantage of progressive disclosure to help people discover content that’s currently hidden.

Make controls easier to use by providing enough space around them and grouping them in logical sections.

Adaptability

• 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

Design a layout that adapts gracefully to context changes while remaining recognizably consistent.

Be prepared for text-size changes.

Preview your app on multiple devices, using different orientations, localizations, and text sizes.

When necessary, scale artwork in response to display changes.

Guides and safe areas

Respect key display and system features in each platform.

Platform considerations

iOS

Aim to support both portrait and landscape orientations.

Prefer a full-bleed interface for your game.

Avoid full-width buttons.

Hide the status bar only when it adds value or enhances your experience.

iPadOS

As someone resizes a window, defer switching to a compact view for as long as possible.

Test your layout at common system-provided sizes, and provide smooth transitions.

Consider a convertible tab bar for adaptive navigation.

macOS

Avoid placing controls or critical information at the bottom of a window.

Avoid displaying content within the camera housing at the top edge of the window.

tvOS

Be prepared for a wide range of TV sizes.

Adhere to the screen’s safe area.

Include appropriate padding between focusable elements.

Grids

• Two-column
• Three-column
• Four-column
• Five-column
• Six-column
• Seven-column
• Eight-column
• Nine-column

Nine-column grid

Include additional vertical spacing for titled rows.

Use consistent spacing.

Make partially hidden content look symmetrical.

visionOS

Consider centering the most important content and controls in your app or game.

Keep a window’s content within its bounds.

If you need to display additional controls that don’t belong within a window, use an ornament.

Make a window’s interactive components easy for people to look at.

watchOS

Design your content to extend from one edge of the screen to the other.

Avoid placing more than two or three controls side by side in your interface.

Support autorotation in views people might want to show others.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/layout

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/materials.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Materials

Liquid Glass

Don’t use Liquid Glass in the content layer.

Use Liquid Glass effects sparingly.

Only use clear Liquid Glass for components that appear over visually rich backgrounds.

• 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.

Standard materials

Choose materials and effects based on semantic meaning and recommended usage.

Help ensure legibility by using vibrant colors on top of materials.

Consider contrast and visual separation when choosing a material to combine with blur and vibrancy effects.

• 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.

Platform considerations

iOS, iPadOS

• `UIVibrancyEffectStyle.label` (default)

• `UIVibrancyEffectStyle.secondaryLabel`

• `UIVibrancyEffectStyle.tertiaryLabel`

• `UIVibrancyEffectStyle.quaternaryLabel`

• `UIVibrancyEffectStyle.fill` (default)

• `UIVibrancyEffectStyle.secondaryFill`

• `UIVibrancyEffectStyle.tertiaryFill`

macOS

Choose when to allow vibrancy in custom views and controls.

Choose a background blending mode that complements your interface design.

visionOS

Prefer translucency to opaque colors in windows.

If necessary, choose materials that help you create visual separations or indicate interactivity in your app.

• 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.

• 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.

watchOS

Use materials to provide context in a full-screen modal view.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/materials

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/motion.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Motion

Best practices

Add motion purposefully, supporting the experience without overshadowing it.

Make motion optional.

Providing feedback

Strive for realistic feedback motion that follows people’s gestures and expectations.

Aim for brevity and precision in feedback animations.

In apps, generally avoid adding motion to UI interactions that occur frequently.

Let people cancel motion.

Consider using animated symbols where it makes sense.

Leveraging platform capabilities

Make sure your game’s motion looks great by default on each platform you support.

Let people customize the visual experience of your game to optimize performance or battery life.

Platform considerations

visionOS

As much as possible, avoid displaying motion at the edges of a person’s field of view.

Help people remain comfortable when showing the movement of large virtual objects.

Consider using fades when you need to relocate an object.

In general, avoid letting people rotate a virtual world.

Consider giving people a stationary frame of reference.

Avoid showing objects that oscillate in a sustained way.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/motion

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/privacy.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Privacy

Best practices

Request access only to data that you actually need.

Be transparent about how your app collects and uses people’s data.

Process data on the device where possible.

Adopt system-defined privacy protections and follow security best practices.

Requesting permission

• 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

Request permission only when your app clearly needs access to the data or resource.

Avoid requesting permission at launch unless the data or resource is required for your app to function.

Write copy that clearly describes how your app uses the ability, data, or resource you’re requesting.

• Example 1
• Example 2
• Example 3

Pre-alert screens, windows, or views

Include only one button and make it clear that it opens the system alert.

Don’t include additional actions in your custom screen or window.

Tracking requests

Never precede the system-provided alert with a custom screen or window that could confuse or mislead people.

• Incentive
• Imitation request
• Alert image
• Alert annotation

Location button

Consider using the location button to give people a lightweight way to share their location for specific app features.

Consider customizing the location button to harmonize with your UI.

• 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.

Protecting data

Avoid relying solely on passwords for authentication.

Store sensitive information in a keychain.

Never store passwords or other secure content in plain-text files.

Avoid inventing custom authentication schemes.

Platform considerations

macOS

Sign your app with a valid Developer ID.

Protect people’s data with app sandboxing.

Avoid making assumptions about who is signed in.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/privacy

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/right-to-left.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Right to left

Text alignment

Adjust text alignment to match the interface direction, if the system doesn’t do so automatically.

Align a paragraph based on its language, not on the current context.

Use a consistent alignment for all text items in a list.

Numbers and characters

Don’t reverse the order of numerals in a specific number.

Reverse the order of numerals that show progress or a counting direction; never flip the numerals themselves.

Controls

Flip controls that show progress from one value to another.

Flip controls that help people navigate or access items in a fixed order.

Preserve the direction of a control that refers to an actual direction or points to an onscreen area.

Visually balance adjacent Latin and RTL scripts when necessary.

Images

Avoid flipping images like photographs, illustrations, and general artwork.

Reverse the positions of images when their order is meaningful.

Interface icons

Flip interface icons that represent text or reading direction.

Consider creating a localized version of an interface icon that displays text.

Flip an interface icon that shows forward or backward motion.

Don’t flip logos or universal signs and marks.

In general, avoid flipping interface icons that depict real-world objects.

Before merely flipping a complex custom interface icon, consider its individual components and the overall visual balance.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/right-to-left

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/sf-symbols.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

SF Symbols

Rendering modes

Confirm that a symbol’s rendering mode works well in every context.

Variable color

Use variable color to communicate change — don’t use it to communicate depth.

Design variants

• 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.

Animations

• 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.

Apply symbol animations judiciously.

Make sure that animations serve a clear purpose in communicating a symbol’s intent.

Use symbol animations to communicate information more efficiently.

Consider your app’s tone when adding animations.

Custom symbols

Use the template as a guide.

• Simple

• Recognizable

• Inclusive

• Directly related to the action or content it represents

Assign negative side margins to your custom symbol if necessary.

Optimize layers to use animations with custom symbols.

Test animations for custom symbols.

Avoid making custom symbols that include common variants, such as enclosures or badges.

Provide alternative text labels for custom symbols.

Don’t design replicas of Apple products.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/sf-symbols

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/spatial-layout.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Spatial layout

Field of view

Center important content within the field of view.

• Upright viewing
• Angled viewing

Avoid anchoring content to the wearer’s head.

Depth

Provide visual cues that accurately communicate the depth of your content.

Use depth to communicate hierarchy.

In general, avoid adding depth to text.

Make sure depth adds value.

Scale

Consider using fixed scale when you want a virtual object to look exactly like a physical object.

Best practices

Avoid displaying too many windows.

Prioritize standard, indirect gestures.

Rely on the Digital Crown to help people recenter windows in their field of view.

Include enough space around interactive components to make them easy for people to look at.

Let people use your app with minimal or no physical movement.

Use the floor to help you place a large immersive experience.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/spatial-layout

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/typography.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Typography

Ensuring legibility

Use font sizes that most people can read easily.

Test legibility in different contexts.

In general, avoid light font weights.

Conveying hierarchy

Adjust font weight, size, and color as needed to emphasize important information and help people visualize hierarchy.

Minimize the number of typefaces you use, even in a highly customized interface.

Prioritize important content when responding to text-size changes.

Using system fonts

Consider using the built-in text styles.

Modify the built-in text styles if necessary.

If necessary, adjust tracking in interface mockups.

Using custom fonts

Make sure custom fonts are legible.

Implement accessibility features for custom fonts.

Supporting Dynamic Type

Make sure your app’s layout adapts to all font sizes.

Increase the size of meaningful interface icons as font size increases.

Keep text truncation to a minimum as font size increases.

Consider adjusting your layout at large font sizes.

Maintain a consistent information hierarchy regardless of the current font size.

Platform considerations

macOS

When necessary, use dynamic system font variants to match the text in standard controls.

visionOS

In general, prefer 2D text.

Make sure text looks good and remains legible when people scale it.

Maximize the contrast between text and the background of its container.

If you need to display text that’s not on a background, consider making it bold to improve legibility.

Keep text facing people as much as possible.

Specifications

iOS, iPadOS Dynamic Type sizes

• xSmall
• Small
• Medium
• Large (default)
• xLarge
• xxLarge
• xxxLarge

iOS, iPadOS larger accessibility type sizes

• AX1
• AX2
• AX3
• AX4
• AX5

watchOS Dynamic Type sizes

• xSmall
• Small
• Large
• xLarge
• xxLarge
• xxxLarge

watchOS larger accessibility type sizes

• AX1
• AX2
• AX3

Tracking values

iOS, iPadOS, visionOS tracking values

• SF Pro
• SF Pro Rounded
• New York

watchOS tracking values

• SF Compact
• SF Compact Rounded

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/typography

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/writing.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Writing

Getting started

Determine your app’s voice.

Match your tone to the context.

Be clear.

Write for everyone.

Best practices

Be action oriented.

Build language patterns.

Adopt capitalization rules that align with your app’s style, then apply them consistently.

Give clear guidance and use consistent language throughout processes with multiple steps.

Use possessive pronouns sparingly.

Write for how people use each device.

Provide clear next steps on any blank screens.

Write clear error messages.

Choose the right delivery method.

Keep settings labels clear and simple.

Show hints in text fields.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/writing