From 34bd90e30d389b00b2475f9e317f97acaf9d46fa Mon Sep 17 00:00:00 2001 From: Anthony Cardinale Date: Wed, 25 Mar 2026 07:52:07 -0400 Subject: [PATCH] Initial release: swift-front skill with Apple HIG integration Combines frontend-design aesthetics with swiftui-pro correctness, grounded in Apple's Human Interface Guidelines (134 articles). Includes curated HIG reference files for typography, color, layout, materials, motion, icons, and components, plus full HIG JSON data for deep lookups. Co-Authored-By: Claude Opus 4.6 --- README.md | 59 + SKILL.md | 228 + data/apple-hig-compact.json | 813 ++ data/apple-hig-index.json | 2439 ++++ data/categories/components.json | 397 + data/categories/foundations.json | 17904 +++++++++++++++++++++++++ data/categories/general.json | 4137 ++++++ data/categories/getting-started.json | 1534 +++ data/categories/inputs.json | 4476 +++++++ data/categories/patterns.json | 6305 +++++++++ data/categories/technologies.json | 12445 +++++++++++++++++ references/hig-color.md | 94 + references/hig-components.md | 62 + references/hig-icons.md | 91 + references/hig-layout.md | 100 + references/hig-materials.md | 82 + references/hig-motion.md | 45 + references/hig-typography.md | 111 + 18 files changed, 51322 insertions(+) create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 data/apple-hig-compact.json create mode 100644 data/apple-hig-index.json create mode 100644 data/categories/components.json create mode 100644 data/categories/foundations.json create mode 100644 data/categories/general.json create mode 100644 data/categories/getting-started.json create mode 100644 data/categories/inputs.json create mode 100644 data/categories/patterns.json create mode 100644 data/categories/technologies.json create mode 100644 references/hig-color.md create mode 100644 references/hig-components.md create mode 100644 references/hig-icons.md create mode 100644 references/hig-layout.md create mode 100644 references/hig-materials.md create mode 100644 references/hig-motion.md create mode 100644 references/hig-typography.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5cde63b --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# swift-front + +A Claude Code skill for building distinctive, production-grade SwiftUI interfaces. Combines bold aesthetic direction from [frontend-design](https://github.com/anthropics/claude-code-plugins/tree/main/skills/frontend-design) with modern SwiftUI correctness from [swiftui-pro](https://github.com/nicklama/swiftui-pro), grounded in Apple's Human Interface Guidelines. + +## What it does + +When invoked (via `/swift-front` or automatically when building SwiftUI views), this skill guides Claude to: + +1. **Design Think** — commit to a bold aesthetic direction before writing code +2. **Check HIG compliance** — load relevant Apple HIG references for the design domain +3. **Implement with correctness** — modern SwiftUI APIs (iOS 26, Swift 6.2), proper data flow, accessibility +4. **Avoid AI slop** — explicit anti-patterns checklist to prevent generic, forgettable interfaces + +## Install + +Clone into your Claude Code skills directory: + +```bash +git clone https://github.com/cardinale/swift-front.git ~/.claude/skills/swift-front +``` + +## Structure + +``` +swift-front/ +├── SKILL.md # Main skill (loaded when invoked) +├── references/ # Curated HIG extracts (loaded on demand) +│ ├── hig-typography.md # Text styles, Dynamic Type, font specs +│ ├── hig-color.md # System colors, dark mode, contrast +│ ├── hig-layout.md # Device dimensions, size classes, safe areas +│ ├── hig-materials.md # Liquid Glass, standard materials, vibrancy +│ ├── hig-motion.md # Animation principles, Reduce Motion +│ ├── hig-icons.md # App icons, SF Symbols, rendering modes +│ └── hig-components.md # Component taxonomy, modality, search +└── data/ # Machine-readable HIG data + ├── apple-hig-compact.json # 45 articles — tips/notes only (39KB) + ├── apple-hig-index.json # 134 articles — navigation index (65KB) + └── categories/ # Full HIG articles by category (~2.2MB) + ├── foundations.json + ├── components.json + ├── patterns.json + ├── technologies.json + ├── inputs.json + ├── general.json + └── getting-started.json +``` + +## HIG Data + +The `data/` directory contains a structured JSON extraction of [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) (134 articles). The curated `references/` files distill the most design-relevant content into scannable markdown. For edge cases, the skill instructs Claude to search the index and read from the full category files. + +## Pairs with + +- **[swiftui-pro](https://github.com/nicklama/swiftui-pro)** — After building with swift-front, use swiftui-pro for full API correctness review +- **[frontend-design](https://github.com/anthropics/claude-code-plugins/tree/main/skills/frontend-design)** — The web equivalent; swift-front adapts its design philosophy for Apple platforms + +## License + +MIT diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..4bcd249 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,228 @@ +--- +name: swift-front +description: Use when building new SwiftUI views, screens, or apps where visual design quality matters - creating distinctive, production-grade iOS interfaces that avoid generic aesthetics. Triggers on requests to build SwiftUI components, design iOS screens, or create visually striking Apple platform interfaces. +--- + +# Swift Front + +Create distinctive, production-grade SwiftUI interfaces with exceptional visual design. Combines bold aesthetic direction with modern SwiftUI correctness, grounded in Apple's Human Interface Guidelines. + +**Core principle:** Every SwiftUI screen should feel *designed*, not *generated*. Commit to a clear aesthetic vision and execute it with the full power of SwiftUI's rendering pipeline. + +## Design Thinking + +Before writing any SwiftUI code, understand the context and commit to a BOLD aesthetic direction: + +- **Purpose**: What does this screen solve? Who uses it — quick glance or deep immersion? +- **Tone**: Pick an extreme and commit: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, liquid glass, skeuomorphic revival. Use these for inspiration but design one true to the aesthetic. +- **Platform Context**: iOS has its own design language — work WITH it. Liquid Glass, materials, SF Symbols, Dynamic Type are tools, not constraints. +- **Differentiation**: What's the ONE thing someone remembers about this interface? + +**CRITICAL**: Bold maximalism and refined minimalism both work. The key is intentionality, not intensity. Generic = forgettable. No two designs should look the same. + +## HIG Compliance Check + +After choosing your aesthetic direction and before implementing, load the relevant HIG reference files to ensure your design works within Apple's guidelines: + +| Building... | Load reference | +|-------------|---------------| +| Typography / text hierarchy | `references/hig-typography.md` | +| Color system / dark mode | `references/hig-color.md` | +| Layout / responsive design | `references/hig-layout.md` | +| Materials / Liquid Glass / depth | `references/hig-materials.md` | +| Animations / transitions | `references/hig-motion.md` | +| Icons / SF Symbols / app icon | `references/hig-icons.md` | +| Navigation / modals / search | `references/hig-components.md` | + +For topics not covered in curated references, search `data/apple-hig-index.json` for the article, then read the full content from `data/categories/.json`. + +### When HIG and Bold Design Conflict + +The swift-front skill encourages breaking conventions — the HIG enforces them. Here's the boundary: + +| HIG Rule Type | Compliance Level | Example | +|---------------|-----------------|---------| +| **Accessibility** | NON-NEGOTIABLE | 44pt min tap targets, Dynamic Type, contrast ratios, Reduce Motion | +| **Component behavior** | STRONGLY RECOMMENDED | NavigationStack patterns, sheet presentation, alert conventions | +| **Visual styling** | SUGGESTIONS — override with intent | Default List appearance, standard spacing, system font defaults | + +You can break visual conventions if you replace them with something *better and intentional*. You cannot break accessibility rules or fundamental component behavior. + +## SwiftUI Aesthetics Guidelines + +### Typography + +- **Never** default to system font without consideration. SF Pro is fine when *intentional*, but explore: + - SF Pro Display for large titles, SF Pro Rounded for playful UIs, SF Mono for data-dense screens + - Custom fonts: `.font(.custom("FontName", size:, relativeTo:))` — always use `relativeTo:` for Dynamic Type + - `@ScaledMetric` for custom sizing that respects accessibility (iOS 18−), `.font(.body.scaled(by:))` (iOS 26+) + - Pair a distinctive display font with a readable body font +- Use `bold()` not `fontWeight(.bold)` — let the system choose context-appropriate weight +- Don't scatter `fontWeight(.medium)` or `.semibold` — every weight choice needs hierarchy purpose +- Avoid `.caption2` (extremely small) and use `.caption` carefully +- HIG minimum sizes: iOS 11pt, macOS 10pt, visionOS 12pt — never go below these + +### Color & Theme + +- Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. +- Create a shared `Design` constants enum for all colors, spacing, corner radii — consistency is non-negotiable +- Use semantic system colors (`.primary`, `.secondary`) as foundation, layer custom accents on top +- `foregroundStyle()` with hierarchical styles (`.secondary`, `.tertiary`) before reaching for manual opacity +- Gradients: `LinearGradient`, `RadialGradient`, `MeshGradient` (iOS 18+), `EllipticalGradient` — use intentionally, not decoratively +- Design dark mode from the start — use asset catalog colors or conditional logic +- Never use UIKit colors (`UIColor`) in SwiftUI code +- HIG contrast: minimum 4.5:1; aim for 7:1 in small text +- Even single-appearance apps must provide light+dark colors for Liquid Glass adaptivity + +### Motion & Animation + +- `withAnimation(.bouncy)` or `.spring()` as default — linear animations feel mechanical +- Chain animations with `completion:` closures, NEVER multiple `withAnimation()` with delays: + +```swift +withAnimation(.spring) { + scale = 2 +} completion: { + withAnimation(.spring) { + scale = 1 + } +} +``` + +- Always provide a value: `.animation(.bouncy, value: score)` — never the deprecated parameterless variant +- Use `@Animatable` macro over manual `animatableData`; mark non-animatable properties `@AnimatableIgnored` +- `sensoryFeedback()` for haptics — pair with visual transitions for multi-sensory delight +- Staggered reveals on appear create more impact than scattered micro-interactions +- `PhaseAnimator` for looping multi-phase sequences, `KeyframeAnimator` for complex choreography +- `contentTransition(.numericText())` for number changes, `.symbolEffect()` for SF Symbol animations +- Respect `accessibilityReduceMotion` — replace large animations with opacity crossfades (HIG: non-negotiable) + +### Spatial Composition + +- Break the grid intentionally. Overlap with `.offset()` or `ZStack` alignment. Asymmetric layouts. +- `containerRelativeFrame()` over `GeometryReader` for responsive sizing +- Generous negative space OR controlled density — never the muddy middle +- `.visualEffect()` for scroll-driven parallax and transforms +- `ScrollView` with `.scrollTargetBehavior(.paging)` or `.viewAligned` for snappy scroll UX +- Never use `UIScreen.main.bounds` — use `containerRelativeFrame()` or `visualEffect()` + +### Materials & Depth + +- `.ultraThinMaterial`, `.regularMaterial`, `.thickMaterial` — native glass effects +- Layer materials over vibrant backgrounds for depth +- `shadow(color:radius:x:y:)` — sparingly but effectively; soft large-radius shadows for elevation +- `clipShape(.rect(cornerRadius:))` — `.continuous` is the default, matches iOS system rounding +- Custom `Shape` conformances for non-rectangular clipping +- `Canvas` for high-performance custom drawing (particles, generative backgrounds, data visualizations) +- `MeshGradient` for rich, organic color fields +- HIG: Liquid Glass is for controls/navigation ONLY — never in the content layer +- HIG: Use `glassEffect(_:in:)` for custom Liquid Glass; regular variant for most, clear variant over media + +### SF Symbols + +- 6000+ symbols — always check for the right one before creating custom assets +- `.symbolEffect(.bounce)`, `.symbolEffect(.pulse)`, `.symbolRenderingMode(.hierarchical)` for rich treatments +- Variable color symbols for progress indicators +- Always include text labels: `Button("Add", systemImage: "plus", action: addItem)` +- HIG: Gradients on symbols (SF Symbols 7+), Draw On/Off animations, Magic Replace + +## Implementation Rules + +Beautiful AND correct — these are non-negotiable: + +1. **Extract views** into separate `View` structs in their own files — never computed properties returning `some View` +2. **Button actions** go in methods, not inline closures +3. **`@Observable`** for shared state (not `ObservableObject`), marked `@MainActor` +4. **`@State`** must be `private`, owned by the creating view +5. **`NavigationStack`** with `navigationDestination(for:)` — never `NavigationView` +6. **Minimum 44×44pt** tap targets — Apple's strict minimum (HIG) +7. **`task()`** over `onAppear()` for async work (auto-cancels on disappear) +8. **Ternary** for toggling modifier values — preserves structural identity, avoids `_ConditionalContent` +9. **`LazyVStack`/`LazyHStack`** in `ScrollView` for large data sets +10. **`#Preview`** — never `PreviewProvider` +11. **`async`/`await`** — never `DispatchQueue` +12. **Each type** in its own Swift file + +**REQUIRED:** For full API correctness validation after implementation, use swiftui-pro. + +## Anti-Patterns — The "AI Slop" Checklist + +NEVER produce SwiftUI that looks like every other AI-generated app: + +| AI Slop | Instead | +|---------|---------| +| Default system font with no hierarchy | Intentional typography with clear display/body pairing | +| Blue accent on white background | Committed palette with dominant + accent strategy | +| `List` with default styling for everything | Custom layouts with intentional spacing and composition | +| Identical padding/spacing everywhere | Varied rhythm — tight grouping + generous breathing room | +| No animations or only `.default` | Spring animations, staggered reveals, symbol effects | +| Gray placeholder backgrounds | Materials, gradients, mesh gradients, Canvas drawings | +| Uniform corner radii | Varied radii — larger containers, tighter chips/badges | +| No haptic feedback | `sensoryFeedback()` on key interactions | +| Every screen looks the same | Each screen has character appropriate to its content | +| Overused purple gradients | Context-specific color stories | + +## Quick Reference — Design Tokens Pattern + +```swift +enum Design { + enum Spacing { + static let xs: CGFloat = 4 + static let sm: CGFloat = 8 + static let md: CGFloat = 16 + static let lg: CGFloat = 24 + static let xl: CGFloat = 32 + static let xxl: CGFloat = 48 + } + + enum Corner { + static let sm: CGFloat = 8 + static let md: CGFloat = 12 + static let lg: CGFloat = 20 + static let pill: CGFloat = .infinity + } + + enum Palette { + static let accent = Color("AccentPrimary") + static let surface = Color("Surface") + static let surfaceElevated = Color("SurfaceElevated") + } +} +``` + +Customize this for each project's aesthetic. Never reuse identical tokens across different apps — each app deserves its own design language. + +## Common Mistakes + +| Mistake | Fix | +|---------|-----| +| `GeometryReader` for responsive layout | `containerRelativeFrame()` or `visualEffect()` | +| `foregroundColor()` | `foregroundStyle()` | +| `cornerRadius()` modifier | `clipShape(.rect(cornerRadius:))` | +| Stored `DateFormatter` properties | `Text(date, format: .dateTime.day().month())` | +| `NavigationView` | `NavigationStack` or `NavigationSplitView` | +| `@StateObject` / `@ObservedObject` | `@State` with `@Observable` classes | +| Icon-only buttons | `Button("Label", systemImage: "icon", action: tap)` | +| `animation()` without value | `.animation(.spring, value: isExpanded)` | +| Manual `animatableData` | `@Animatable` macro | +| `DispatchQueue.main.async` | `@MainActor` / `Task` / `async`/`await` | +| `onTapGesture()` for buttons | `Button` (accessible by default) | +| `Binding(get:set:)` in body | `@State` binding + `onChange()` | +| `overlay(Text("x"))` | `overlay { Text("x") }` | +| `String(format: "%.2f")` | `Text(value, format: .number.precision(...))` | +| Liquid Glass in content layer | Liquid Glass for controls/navigation only | +| Ignoring Reduce Motion | Always provide opacity crossfade fallback | + +## References + +- `references/hig-typography.md` — Text sizes, Dynamic Type scales, font specs per platform +- `references/hig-color.md` — System colors, dark mode, Liquid Glass color, contrast requirements +- `references/hig-layout.md` — Safe areas, device dimensions, size classes, grid specs +- `references/hig-materials.md` — Liquid Glass variants, standard materials, vibrancy levels +- `references/hig-motion.md` — Animation principles, Reduce Motion, visionOS motion comfort +- `references/hig-icons.md` — App icon specs, SF Symbols rendering/animations, standard symbols +- `references/hig-components.md` — Component categories, modality rules, search patterns +- `data/apple-hig-compact.json` — Quick-lookup tips/notes from 45 HIG articles +- `data/apple-hig-index.json` — Full 134-article index for deep lookups + +Remember: Claude is capable of extraordinary creative work in SwiftUI. Don't produce another generic app — commit to a vision and execute with precision. Show what's possible when design intentionality meets SwiftUI's full rendering power. diff --git a/data/apple-hig-compact.json b/data/apple-hig-compact.json new file mode 100644 index 0000000..974eca6 --- /dev/null +++ b/data/apple-hig-compact.json @@ -0,0 +1,813 @@ +{ + "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", + "format": "compact-guidelines-only" + }, + "articles": [ + { + "title": "App icons", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/app-icons", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Appearances" + } + ] + }, + { + "title": "Apple Pay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pay", + "platforms": [], + "guidelines": [ + { + "sentiment": "tip", + "text": "TipIt’s important to understand the difference between Apple Pay and In-app purchase. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and tickets for events; and for donations. Use In-App Purchase in your app to sell virtual goods, such as premium content for your app, and subscriptions for digital content.", + "context": "Overview" + }, + { + "sentiment": "note", + "text": "NoteFor privacy reasons, your app or website has limited access to data until people attempt to authorize a transaction. Prior to authorization, only the card type and a redacted shipping address are accessible. It’s critical to display errors when authorization fails, but to the extent possible, you also need to attempt to validate available information and report problems before authorization.", + "context": "Data validation" + }, + { + "sentiment": "note", + "text": "NoteIf the size you specify doesn’t accommodate the translated title for the type of payment button you’re using, the system automatically replaces it with the plain Apple Pay button shown below on the left. There is no automatic replacement for the Set up Apple Pay button.", + "context": "Button size and position" + } + ] + }, + { + "title": "Apple Pencil and Scribble", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteThe squeeze gesture is available only when the paired iPad screen is on and while the Apple Pencil Pro is not directly contacting it. Because squeeze works when there’s distance between Apple Pencil Pro and iPad, people might not always be visually aware of the gesture’s onscreen result.", + "context": "Squeeze" + } + ] + }, + { + "title": "Augmented reality", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/augmented-reality", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteThe following guidance applies to apps that run in iOS and iPadOS. To learn about using ARKit to create immersive augmented reality experiences in visionOS, see ARKit.", + "context": "Overview" + }, + { + "sentiment": "tip", + "text": "TipRegardless of the purpose of your app, don’t use scaling as a way to adjust the distance of an object. If you enlarge a distant object in an effort to make it appear closer, the result is a larger object that still looks far away.", + "context": "Designing object interactions" + } + ] + }, + { + "title": "Buttons", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/buttons", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Content" + }, + { + "sentiment": "note", + "text": "NoteIn visionOS, buttons don’t support custom hover effects.", + "context": "visionOS" + } + ] + }, + { + "title": "Complications", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/complications", + "platforms": [], + "guidelines": [ + { + "sentiment": "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).", + "context": "Overview" + }, + { + "sentiment": "note", + "text": "NoteThe system applies a circular mask to each image.", + "context": "Circular" + }, + { + "sentiment": "note", + "text": "NoteThe system applies a circular mask to the circular, open-gauge, and closed-gauge images.", + "context": "Circular" + }, + { + "sentiment": "note", + "text": "NoteThe system applies a circular mask to each image.", + "context": "Corner" + }, + { + "sentiment": "note", + "text": "NoteBoth large-image layouts automatically include a four-point corner radius.", + "context": "Rectangular" + }, + { + "sentiment": "note", + "text": "NoteIn each stack measurement, the width value represents the maximum size.", + "context": "Circular small" + }, + { + "sentiment": "note", + "text": "NoteIn each stack measurement, the width value represents the maximum size.", + "context": "Modular small" + }, + { + "sentiment": "note", + "text": "NoteIn each stack measurement, the width value represents the maximum size.", + "context": "Extra large" + } + ] + }, + { + "title": "Designing for visionOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantWhen building your app for Apple Vision Pro, be sure to consider the unique characteristics of the device and its spatial computing environment, and pay special attention to your user’s safety; for more details about these characteristics, see Apple Vision Pro User Guide. For example, Apple Vision Pro should not be used while operating a vehicle or heavy machinery. The device is also not designed to be used while moving around unsafe environments such as near balconies, streets, stairs, or other potential hazards. Note that Apple Vision Pro is designed to be fit and used only by individuals 13 years of age or older.", + "context": "Overview" + } + ] + }, + { + "title": "Digital Crown", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/digital-crown", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteApps don’t respond to presses on the Digital Crown because watchOS reserves these interactions for system-provided functionality like revealing the Home Screen.", + "context": "Apple Watch" + } + ] + }, + { + "title": "Dock menus", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteAlthough iOS and iPadOS don’t support a Dock menu, people can reveal a similar menu of system-provided and custom items — called Home Screen quick actions — when they long press an app icon on the Home Screen or in the Dock. For guidance, see Home Screen quick actions.", + "context": "Overview" + } + ] + }, + { + "title": "Eyes", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/eyes", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantTo help preserve people’s privacy, visionOS doesn’t provide direct information about where people are looking before they tap. When you use system-provided components, visionOS automatically tells you when people tap the component. For developer guidance, see Adopting best practices for privacy and user preferences.", + "context": "Overview" + } + ] + }, + { + "title": "Focus and selection", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/focus-and-selection", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteWhen people look at a virtual object to identify it as the object they want to interact with, the system uses the hover effect, not a focus effect, to provide visual feedback (for guidance, see Eyes). The hover effect isn’t related to the focus system.", + "context": "visionOS" + } + ] + }, + { + "title": "Game Center", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-center", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteIn visionOS, the locations of the access point vary based on game type, such as immersive or volume-based. For developer guidance, see Adding an access point to your game.", + "context": "Integrating the access point" + }, + { + "sentiment": "note", + "text": "NoteBe mindful of how cropping might affect your leaderboard artwork. In iOS, iPadOS, and macOS, the system crops artwork for leaderboards that are part of a leaderboard set. In tvOS, the focus effect on leaderboard artwork may crop your images at the edges of some layers. Make sure your primary content stays comfortably visible in both these scenarios.", + "context": "Leaderboards" + } + ] + }, + { + "title": "Gestures", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/gestures", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteThe system overlay is the default method of accessing Control Center in visionOS 2 and later. The visionOS 1 behavior (looking upward) remains available as an accessibility setting.", + "context": "Working with system overlays in visionOS" + }, + { + "sentiment": "note", + "text": "NoteApps and games that you built for visionOS 1 defer the system overlay behavior by default. When a person looks at their palm with your app running in a Full Space, the Home indicator won’t appear unless they tap first.", + "context": "Working with system overlays in visionOS" + } + ] + }, + { + "title": "Gyroscope and accelerometer", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantIf your experience needs to access motion data from a device, you must provide copy that explains why. The first time your app or game tries to access this type of data, the system includes your copy in a permission request, where people can grant or deny access.", + "context": "Best practices" + } + ] + }, + { + "title": "HealthKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/healthkit", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantIf your app doesn’t provide health and fitness functionality, don’t request access to people’s private health data.", + "context": "Overview" + } + ] + }, + { + "title": "HomeKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/homekit", + "platforms": [], + "guidelines": [ + { + "sentiment": "tip", + "text": "TipThe HomeKit API uses the term action set instead of scene. In your app’s UI, always use the term scene.", + "context": "Actions and scenes" + } + ] + }, + { + "title": "Images", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/images", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Layered images" + }, + { + "sentiment": "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.", + "context": "Layered images" + } + ] + }, + { + "title": "In-app purchase", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase", + "platforms": [], + "guidelines": [ + { + "sentiment": "tip", + "text": "TipIn-app purchase and Apple Pay are different technologies that support different use cases. Use in-app purchase to sell virtual goods in your app, such as premium content for your app and subscriptions for digital content. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and event tickets; and for donations.", + "context": "Overview" + }, + { + "sentiment": "note", + "text": "NoteFor apps with exceptionally large, frequently updated catalogs of one-time purchases or subscription content from multiple creators, or apps that provide subscriptions with optional add-on content as a single purchase within the app, the Advanced Commerce API allows you to manage your In-App Purchase catalog directly. See the Advanced Commerce API App Store support page for an overview, and see Advanced Commerce API for developer guidance.", + "context": "Overview" + } + ] + }, + { + "title": "Keyboards", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/keyboards", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantAlthough iPadOS supports keyboard navigation in text fields, text views, and sidebars, and provides APIs you can use to support it in collection views and other custom views, avoid supporting keyboard navigation for controls, such as buttons, segmented controls, and switches. Instead, let people use Full Keyboard Access to activate controls, navigate to all onscreen components, and perform gesture-based interactions like drag and drop. For guidance, see iPadOS; for developer guidance, see Focus-based navigation.", + "context": "Best practices" + }, + { + "sentiment": "tip", + "text": "TipSome languages require modifier keys to generate certain characters. For example, on a French keyboard, Option-5 generates the “{“ character. It’s usually safe to use the Command key as a modifier, but avoid using an additional modifier with characters that aren’t available on all keyboards. If you must use a modifier other than Command, prefer using it only with the alphabetic characters.", + "context": "Custom keyboard shortcuts" + } + ] + }, + { + "title": "Launching", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/launching", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteUnlike the layered images throughout much of a tvOS app, the launch screen is static.", + "context": "tvOS" + } + ] + }, + { + "title": "Layout", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/layout", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "visionOS" + }, + { + "sentiment": "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.", + "context": "iOS, iPadOS device screen dimensions" + } + ] + }, + { + "title": "Mac Catalyst", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/mac-catalyst", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "Developer noteTo discover how views and controls can change when you create a Mac app using Mac Catalyst, download UIKit Catalog: Creating and customizing views and controls and build the macOS target.", + "context": "Before you start" + }, + { + "sentiment": "note", + "text": "Developer noteWhen you adopt the Mac idiom, the unscaled views and interface elements report different metrics, often resulting in a significant amount of additional work. To reduce the amount of work, avoid using fixed font, view, or layout sizes. For developer guidance, see Choosing a user interface idiom for your Mac app.", + "context": "Choose an idiom" + }, + { + "sentiment": "note", + "text": "Developer noteThe system sends the two touches in the pinch and rotate gestures to the view under the pointer, not the view under each touch.", + "context": "Inputs" + }, + { + "sentiment": "note", + "text": "Developer noteTo support keyboard shortcuts for menu commands, use UIKeyCommand. For developer guidance, see Adding menus and shortcuts to the menu bar and user interface.", + "context": "Menus" + }, + { + "sentiment": "note", + "text": "Developer noteTo add and remove custom app menus, use UIMenuBuilder and add menu items that represent your iPad app’s commands as menu items with UICommand.", + "context": "Menus" + } + ] + }, + { + "title": "Managing accounts", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-accounts", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantIf legal requirements compel your app to maintain accounts or information — such as digital health records — or to follow a specific account-deletion process, clearly describe the situation so people can understand the information or accounts you must maintain and the process you must follow.", + "context": "Deleting accounts" + }, + { + "sentiment": "note", + "text": "Developer noteIf people used Sign in with Apple to create an account within your app, you revoke the associated tokens when they delete their account. See Token revocation.", + "context": "Deleting accounts" + }, + { + "sentiment": "note", + "text": "NoteEven if people didn’t use your app to purchase the subscription, you still need to support account deletion.", + "context": "Deleting accounts" + } + ] + }, + { + "title": "Managing notifications", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-notifications", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantEven though a Focus might delay the delivery of a notification alert, the notification itself is available as soon as it arrives.", + "context": "Integrating with Focus" + }, + { + "sentiment": "note", + "text": "NoteBecause a Critical notification can override the Ring/Silent switch and break through scheduled delivery and Focus, you must get an entitlement to send one.", + "context": "Integrating with Focus" + } + ] + }, + { + "title": "Maps", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/maps", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteThe Apple logo and legal link aren’t shown on maps that are smaller than 200x100 pixels.", + "context": "Best practices" + }, + { + "sentiment": "note", + "text": "Developer noteIn websites, you can embed a custom map that displays a place card by default for a single place that you specify. For developer guidance, see Displaying place information using the Maps Embed API.", + "context": "Displaying place cards in a map" + }, + { + "sentiment": "important", + "text": "ImportantIf you don’t display a place card directly within a map view, you must include a map in the place card. For developer guidance, see mapItemDetailSheet(item:displaysMap:) and init(mapItem:displaysMap:).", + "context": "Adding place cards outside of a map" + } + ] + }, + { + "title": "Materials", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/materials", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "visionOS" + } + ] + }, + { + "title": "Menus", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/menus", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Overview" + }, + { + "sentiment": "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.", + "context": "Labels" + } + ] + }, + { + "title": "Motion", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/motion", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "visionOS" + }, + { + "sentiment": "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.", + "context": "watchOS" + } + ] + }, + { + "title": "Multitasking", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/multitasking", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteApps don’t control multitasking configurations or receive any indication of the ones that people choose.", + "context": "iPadOS" + }, + { + "sentiment": "note", + "text": "NoteWhen an app is the Now Playing app, closing its window automatically pauses audio playback; if people want to resume playback, they can do so in Control Center without opening the window.", + "context": "visionOS" + } + ] + }, + { + "title": "Playing audio", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-audio", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantIn visionOS, as in every platform, avoid communicating important information using only sound. Always provide additional ways to help people understand your app. For guidance, see Accessibility.", + "context": "visionOS" + } + ] + }, + { + "title": "Privacy", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/privacy", + "platforms": [], + "guidelines": [ + { + "sentiment": "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).", + "context": "Location button" + }, + { + "sentiment": "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.", + "context": "Location button" + } + ] + }, + { + "title": "Pull-down buttons", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteYou can also let people reveal a pull-down menu by performing a specific gesture on a button. For example, in iOS 14 and later, Safari responds to a touch and hold gesture on the Tabs button by displaying a menu of tab-related actions, like New Tab and Close All Tabs.", + "context": "iOS, iPadOS" + } + ] + }, + { + "title": "Settings", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/settings", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteIn games, players tend to adjust their approach to a specific task as part of the gameplay, not as a settings option to change.", + "context": "Task-specific options" + } + ] + }, + { + "title": "SF Symbols", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/sf-symbols", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Custom symbols" + } + ] + }, + { + "title": "SharePlay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/shareplay", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteDuring a shared activity, the system helps preserve people’s privacy by obscuring some visual details about wearers. In addition, a person can adjust their spatial Persona if they want. Although the system can place spatial Personas shoulder to shoulder and it supports shared gestures like a handshake or “high five,” spatial Personas remain apart.", + "context": "visionOS" + } + ] + }, + { + "title": "Sidebars", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/sidebars", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "iPadOS" + } + ] + }, + { + "title": "Siri", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri", + "platforms": [], + "guidelines": [ + { + "sentiment": "tip", + "text": "TipIf your action’s primary purpose is to retrieve information or show something to people — like displaying a sports score or the weather — use the information category. Using a different category requires people to make additional taps to get the information.", + "context": "Design a custom intent" + }, + { + "sentiment": "note", + "text": "Developer noteThe Add to Siri method for adding shortcuts is no longer supported. See App Shortcuts for ways to integrate your app with Siri and the system.", + "context": "Shortcuts and suggestions" + }, + { + "sentiment": "note", + "text": "NoteUse translations of your app name and the word Shortcuts — but not Siri — when referring to them in a localized context.", + "context": "Referring to Shortcuts" + } + ] + }, + { + "title": "Spatial layout", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/spatial-layout", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantThe system doesn’t provide information about a person’s field of view.", + "context": "Field of view" + } + ] + }, + { + "title": "Tab bars", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/tab-bars", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "iPadOS" + } + ] + }, + { + "title": "Tap to Pay on iPhone", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteTap to Pay on iPhone works alongside your existing payment-acceptance hardware and accessories.", + "context": "Overview" + }, + { + "sentiment": "note", + "text": "NoteIf your PSP offers an SDK that supplies user interfaces for experiences like showing a tap result, see the documentation the PSP provides.", + "context": "Overview" + }, + { + "sentiment": "important", + "text": "ImportantUse the “Tap to Pay on iPhone” label only for payment actions. For language you can use for nonpayment actions, see Additional interactions.", + "context": "Checking out" + } + ] + }, + { + "title": "The menu bar", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/the-menu-bar", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantThe View menu doesn’t include items for navigating between or managing specific windows; the Window menu provides these commands.", + "context": "View menu" + }, + { + "sentiment": "important", + "text": "ImportantThe Window menu doesn’t help people customize the appearance of windows or close them. To customize a window, people use commands in the View menu; to close a window, people choose Close in the File menu.", + "context": "Window menu" + }, + { + "sentiment": "tip", + "text": "TipmacOS automatically sets the width of a menu to hold the widest item, including dynamic menu items.", + "context": "Dynamic menu items" + } + ] + }, + { + "title": "Toolbars", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/toolbars", + "platforms": [], + "guidelines": [ + { + "sentiment": "note", + "text": "NoteThe system automatically adds an overflow menu in macOS or iPadOS when items no longer fit. Don’t add an overflow menu manually, and avoid layouts that cause toolbar items to overflow by default.", + "context": "Best practices" + } + ] + }, + { + "title": "Typography", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/typography", + "platforms": [], + "guidelines": [ + { + "sentiment": "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.", + "context": "Using system fonts" + }, + { + "sentiment": "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.", + "context": "Using system fonts" + }, + { + "sentiment": "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.", + "context": "Using system fonts" + } + ] + }, + { + "title": "Wallet", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/wallet", + "platforms": [], + "guidelines": [ + { + "sentiment": "important", + "text": "ImportantPoster event tickets aren’t compatible with tickets that require a QR code or barcode for entry.", + "context": "Event tickets" + }, + { + "sentiment": "important", + "text": "ImportantIn every style, watchOS crops the strip image to fit the aspect ratio of the card interface and may crop white space from other images.", + "context": "Passes for Apple Watch" + }, + { + "sentiment": "note", + "text": "Developer noteApple doesn’t create or see the ID documents that people add to Wallet, and when people agree to share identifying information with your app, you receive only encrypted data that isn’t readable on the device. For developer guidance, see Requesting identity data from a Wallet pass.", + "context": "Identity verification" + }, + { + "sentiment": "note", + "text": "NoteDimensions for the logo, primary logo, and secondary logo images are the maximum — not the required — values. For example, if you create a primary logo image that measures 30x30 points, you don’t need to add unnecessary padding so that it measures the maximum 126x30 points.", + "context": "Pass image dimensions" + } + ] + }, + { + "title": "Windows", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/windows", + "platforms": [], + "guidelines": [ + { + "sentiment": "tip", + "text": "TipIf you only need to let people view one file, you can present it without creating your own window, but you must support multiple windows in your app. For developer guidance, see QLPreviewSceneActivationConfiguration.", + "context": "iPadOS" + }, + { + "sentiment": "note", + "text": "NoteSome windows — typically, panels like Colors or Fonts — become the key window only when people click the window’s title bar or a component that requires keyboard input, such as a text field.", + "context": "macOS window states" + }, + { + "sentiment": "note", + "text": "NotevisionOS also defines the plain window style, which is similar to the default style, except that the upright plane doesn’t use the glass background. For developer guidance, see PlainWindowStyle.", + "context": "visionOS" + } + ] + } + ] +} \ No newline at end of file diff --git a/data/apple-hig-index.json b/data/apple-hig-index.json new file mode 100644 index 0000000..2e3222c --- /dev/null +++ b/data/apple-hig-index.json @@ -0,0 +1,2439 @@ +{ + "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", + "format": "index" + }, + "articles": [ + { + "title": "Components", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/components", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Content", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/content", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Layout and organization", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/layout-and-organization", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Menus and actions", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/menus-and-actions", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Navigation and search", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/navigation-and-search", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Presentation", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/presentation", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Selection and input", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/selection-and-input", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Status", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/status", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "System experiences", + "category": "components", + "url": "https://developer.apple.com/design/human-interface-guidelines/system-experiences", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Accessibility", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/accessibility", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Vision", + "Hearing", + "Mobility", + "Speech", + "Cognitive", + "Platform considerations", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "App icons", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/app-icons", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Layer design", + "Icon shape", + "Design", + "Visual effects", + "Appearances", + "Platform considerations", + "tvOS", + "visionOS", + "watchOS", + "Specifications", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Branding", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/branding", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related" + ] + }, + { + "title": "Buttons", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/buttons", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Style", + "Content", + "Role", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Push buttons", + "Square buttons", + "Help buttons", + "Image buttons", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Color", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/color", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Inclusive color", + "System colors", + "Liquid Glass color", + "Color management", + "iOS, iPadOS", + "macOS", + "App accent colors", + "tvOS", + "visionOS", + "watchOS", + "System colors", + "iOS, iPadOS system gray colors", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Complications", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/complications", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Visual design", + "Circular", + "Corner", + "Inline", + "Rectangular", + "Circular small", + "Modular small", + "Modular large", + "Extra large", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Dark Mode", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/dark-mode", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Dark Mode colors", + "Icons and images", + "Text", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Related", + "Change log" + ] + }, + { + "title": "Disclosure controls", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/disclosure-controls", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Disclosure triangles", + "Disclosure buttons", + "Platform considerations", + "iOS, iPadOS, visionOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Foundations", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/foundations", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Icons", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/icons", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Standard icons", + "Editing", + "Selection", + "Text formatting", + "Search", + "Sharing and exporting", + "Users and accounts", + "Ratings", + "Layer ordering", + "Other", + "Platform considerations", + "Document icons", + "Related", + "Change log" + ] + }, + { + "title": "Images", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/images", + "summary": "", + "platforms": [], + "sections": [ + "Resolution", + "Formats", + "Best practices", + "Platform considerations", + "tvOS", + "Parallax effect", + "Layered images", + "visionOS", + "Spatial photos and spatial scenes", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Immersive experiences", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/immersive-experiences", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Immersion and passthrough", + "Immersion styles", + "Best practices", + "Promoting comfort", + "Transitioning between immersive styles", + "Displaying virtual hands", + "Creating an environment", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Inclusion", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/inclusion", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Inclusive by design", + "Welcoming language", + "Being approachable", + "Gender identity", + "People and settings", + "Avoiding stereotypes", + "Accessibility", + "Languages", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Layout", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/layout", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Visual hierarchy", + "Adaptability", + "Guides and safe areas", + "iOS", + "iPadOS", + "macOS", + "tvOS", + "Grids", + "Two-column grid", + "Three-column grid", + "Four-column grid", + "Five-column grid", + "Six-column grid", + "Seven-column grid", + "Eight-column grid", + "Nine-column grid", + "visionOS", + "watchOS", + "iOS, iPadOS device screen dimensions", + "iOS, iPadOS device size classes", + "watchOS device screen dimensions", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Materials", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/materials", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Liquid Glass", + "Standard materials", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Menus", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/menus", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Labels", + "Icons", + "Organization", + "Submenus", + "Toggled items", + "In-game menus", + "Platform considerations", + "iOS, iPadOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Motion", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/motion", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Providing feedback", + "Leveraging platform capabilities", + "Platform considerations", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Ornaments", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/ornaments", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Privacy", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/privacy", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Requesting permission", + "Pre-alert screens, windows, or views", + "Tracking requests", + "Location button", + "Protecting data", + "Platform considerations", + "macOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Right to left", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/right-to-left", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Text alignment", + "Numbers and characters", + "Controls", + "Images", + "Interface icons", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "SF Symbols", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/sf-symbols", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Rendering modes", + "Gradients", + "Variable color", + "Weights and scales", + "Design variants", + "Animations", + "Custom symbols", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Scroll views", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/scroll-views", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Scroll edge effects", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Sidebars", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/sidebars", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS", + "iPadOS", + "macOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Sliders", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/sliders", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Spatial layout", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/spatial-layout", + "summary": "", + "platforms": [], + "sections": [ + "Field of view", + "Depth", + "Scale", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Split views", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/split-views", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "iOS", + "iPadOS", + "macOS", + "tvOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Tab bars", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/tab-bars", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS", + "iPadOS", + "tvOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Toggles", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/toggles", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Switches", + "Checkboxes", + "Radio buttons", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Typography", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/typography", + "summary": "", + "platforms": [], + "sections": [ + "Ensuring legibility", + "Conveying hierarchy", + "Using system fonts", + "Using custom fonts", + "Supporting Dynamic Type", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "watchOS", + "Specifications", + "xSmall", + "Small", + "Medium", + "Large (default)", + "xLarge", + "xxLarge", + "xxxLarge", + "AX1", + "AX2", + "AX3", + "AX4", + "AX5", + "macOS built-in text styles", + "tvOS built-in text styles", + "xSmall", + "Small (default 38mm)", + "Large (default 40mm/41mm/42mm)", + "xLarge (default 44mm/45mm/49mm)", + "xxLarge", + "xxxLarge", + "AX1", + "AX2", + "AX3", + "SF Pro", + "SF Pro Rounded", + "New York", + "macOS tracking values", + "tvOS tracking values", + "SF Compact", + "SF Compact Rounded", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Writing", + "category": "foundations", + "url": "https://developer.apple.com/design/human-interface-guidelines/writing", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Getting started", + "Best practices", + "Platform considerations", + "Related", + "Change log" + ] + }, + { + "title": "Activity views", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/activity-views", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Share and action extensions", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Context menus", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/context-menus", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Content", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Dock menus", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Edit menus", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/edit-menus", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Content", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Home Screen quick actions", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Panels", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/panels", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "HUD-style panels", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Path controls", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/path-controls", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Pop-up buttons", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iPadOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Popovers", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/popovers", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Pull-down buttons", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Search fields", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/search-fields", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Scope controls and tokens", + "Platform considerations", + "iOS", + "Search in a tab bar", + "Search in a toolbar", + "Search as an inline field", + "iPadOS, macOS", + "tvOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Segmented controls", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/segmented-controls", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Content", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Status bars", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/status-bars", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Platform considerations", + "Developer documentation" + ] + }, + { + "title": "The menu bar", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/the-menu-bar", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Anatomy", + "Best practices", + "App menu", + "File menu", + "Edit menu", + "Format menu", + "View menu", + "App-specific menus", + "Window menu", + "Help menu", + "Dynamic menu items", + "Platform considerations", + "iPadOS", + "macOS", + "Menu bar extras", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Token fields", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/token-fields", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Toolbars", + "category": "general", + "url": "https://developer.apple.com/design/human-interface-guidelines/toolbars", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Titles", + "Navigation", + "Actions", + "Item groupings", + "Platform considerations", + "iOS", + "iPadOS", + "macOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Designing for games", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-games", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Jump into gameplay", + "Look stunning on every display", + "Enable intuitive interactions", + "Welcome everyone", + "Adopt Apple technologies", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Designing for iOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-ios", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation" + ] + }, + { + "title": "Designing for iPadOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-ipados", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation" + ] + }, + { + "title": "Designing for macOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-macos", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation" + ] + }, + { + "title": "Designing for tvOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-tvos", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Designing for visionOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Designing for watchOS", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Getting started", + "category": "getting-started", + "url": "https://developer.apple.com/design/human-interface-guidelines/getting-started", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Action button", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/action-button", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS", + "watchOS", + "Related", + "Change log" + ] + }, + { + "title": "Apple Pencil and Scribble", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Hover", + "Double tap", + "Squeeze", + "Barrel roll", + "Scribble", + "Custom drawing", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Camera Control", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/camera-control", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Anatomy", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Digital Crown", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/digital-crown", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Apple Vision Pro", + "Apple Watch", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Eyes", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/eyes", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Making items easy to see", + "Encouraging interaction", + "Custom hover effects", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Focus and selection", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/focus-and-selection", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iPadOS", + "tvOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Game controls", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-controls", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Touch controls", + "Physical controllers", + "Keyboards", + "Platform considerations", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Gestures", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/gestures", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Custom gestures", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "Designing custom gestures in visionOS", + "Working with system overlays in visionOS", + "Double tap", + "Standard gestures", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Gyroscope and accelerometer", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "Inputs", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/inputs", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Keyboards", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/keyboards", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Standard keyboard shortcuts", + "Custom keyboard shortcuts", + "Platform considerations", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Nearby interactions", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/nearby-interactions", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Device usage", + "Platform considerations", + "iOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Pointing devices", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/pointing-devices", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iPadOS", + "Pointer shape and content effects", + "Pointer accessories", + "Pointer magnetism", + "Standard pointers and effects", + "Customizing pointers", + "macOS", + "Pointers", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Remotes", + "category": "inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/remotes", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Gestures", + "Buttons", + "Compatible remotes", + "Platform considerations", + "Related" + ] + }, + { + "title": "Charting data", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/charting-data", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Designing effective charts", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Collaboration and sharing", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Drag and drop", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/drag-and-drop", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Providing feedback", + "Accepting drops", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Entering data", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/entering-data", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "macOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Feedback", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/feedback", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "watchOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "File management", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/file-management", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Creating and opening files", + "Saving work", + "Quick Look previews", + "Platform considerations", + "Document launcher", + "File provider app extension", + "Custom file management", + "Finder Sync extensions", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Going full screen", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/going-full-screen", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Launching", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/launching", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Launch screens", + "Platform considerations", + "iOS, iPadOS", + "tvOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Live-viewing apps", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/live-viewing-apps", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "EPG experience", + "Cloud DVR", + "Platform considerations", + "Related" + ] + }, + { + "title": "Loading", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/loading", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Showing progress", + "Platform considerations", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Managing accounts", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-accounts", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Deleting accounts", + "TV provider accounts", + "Platform considerations", + "tvOS", + "watchOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Managing notifications", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-notifications", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Integrating with Focus", + "Best practices", + "Sending marketing notifications", + "Platform considerations", + "watchOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Modality", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/modality", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Multitasking", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/multitasking", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS", + "iPadOS", + "macOS", + "tvOS", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Offering help", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/offering-help", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Creating tips", + "Platform considerations", + "macOS, visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Onboarding", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/onboarding", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Additional content", + "Additional requests", + "Platform considerations", + "Related", + "Change log" + ] + }, + { + "title": "Patterns", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/patterns", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "Playing audio", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-audio", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Handling interruptions", + "iOS, iPadOS", + "macOS", + "tvOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Playing haptics", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Custom haptics", + "iOS", + "Notification", + "Impact", + "Selection", + "macOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Playing video", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-video", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Integrating with the TV app", + "Loading content", + "Exiting playback", + "Platform considerations", + "tvOS", + "visionOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Printing", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/printing", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Platform considerations", + "macOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Ratings and reviews", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Searching", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/searching", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Systemwide search", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Settings", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/settings", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "General settings", + "Task-specific options", + "System settings", + "Platform considerations", + "macOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Undo and redo", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/undo-and-redo", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iOS, iPadOS", + "macOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "Windows", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/windows", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "iPadOS", + "macOS", + "macOS window anatomy", + "macOS window states", + "visionOS", + "visionOS windows", + "visionOS volumes", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Workouts", + "category": "patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/workouts", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "AirPlay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/airplay", + "summary": "", + "platforms": [], + "sections": [ + "Best practices", + "Using AirPlay icons", + "Black AirPlay icon", + "White AirPlay icon", + "Custom color AirPlay icon", + "Referring to AirPlay", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Always On", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/always-on", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "App Clips", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/app-clips", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Designing your App Clip", + "Preserving privacy", + "Showcasing your app", + "Limiting notifications", + "Creating App Clips for businesses", + "Creating content for an App Clip card", + "App Clip Codes", + "Interacting with App Clip Codes", + "Displaying App Clip Codes", + "Using clear messaging", + "Customizing your App Clip Code", + "Printing guidelines", + "Verifying your printer’s calibration", + "Legal requirements", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Apple Pay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pay", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Offering Apple Pay", + "Streamlining checkout", + "Customizing the payment sheet", + "Displaying a website icon", + "Handling errors", + "Data validation", + "Payment processing", + "Supporting subscriptions", + "Supporting donations", + "Using Apple Pay buttons", + "Button types", + "Button styles", + "Black", + "White with outline", + "White", + "Button size and position", + "Apple Pay mark", + "Referring to Apple Pay", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Augmented reality", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/augmented-reality", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Providing coaching", + "Helping people place objects", + "Designing object interactions", + "Offering a multiuser experience", + "Reacting to real-world objects", + "Communicating with people", + "Handling interruptions", + "Suggesting problem resolutions", + "Icons and badges", + "Platform considerations", + "visionOS", + "Related", + "Developer documentation" + ] + }, + { + "title": "CarPlay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/carplay", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "iPhone interactions", + "Audio", + "Layout", + "Color", + "Icons and images", + "Error handling", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "CareKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/carekit", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Data and privacy", + "HealthKit integration", + "Motion data", + "Photos", + "ResearchKit integration", + "CareKit views", + "Tasks", + "Charts", + "Contact views", + "Notifications", + "Symbols and branding", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Game Center", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-center", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Accessing Game Center", + "Integrating the access point", + "Using custom UI", + "Achievements", + "Integrating achievements into your game", + "Creating achievement images", + "Leaderboards", + "Challenges", + "Multiplayer activities", + "Platform considerations", + "tvOS", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Generative AI", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/generative-ai", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Transparency", + "Privacy", + "Models and datasets", + "Inputs", + "Outputs", + "Continuous improvement", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "HealthKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/healthkit", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Privacy protection", + "Activity rings", + "Apple Health icon", + "Editorial guidelines", + "Platform considerations", + "Related", + "Developer documentation" + ] + }, + { + "title": "HomeKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/homekit", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Terminology and layout", + "Homes", + "Rooms", + "Accessories, services, and characteristics", + "Actions and scenes", + "Automations", + "Zones", + "Setup", + "Help people choose useful names", + "Siri interactions", + "Custom functionality", + "Cameras", + "Using HomeKit icons", + "Styles", + "Black HomeKit icon", + "White HomeKit icon", + "Custom color HomeKit icon", + "Referring to HomeKit", + "Referencing HomeKit and the Home app", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "ID Verifier", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/id-verifier", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "In-app purchase", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Supporting Family Sharing", + "Providing help with in-app purchases", + "Auto-renewable subscriptions", + "Making signup effortless", + "Supporting offer codes", + "Helping people manage their subscriptions", + "Platform considerations", + "watchOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Live Photos", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/live-photos", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "visionOS", + "Developer documentation" + ] + }, + { + "title": "Mac Catalyst", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/mac-catalyst", + "summary": "", + "platforms": [], + "sections": [ + "Before you start", + "Choose an idiom", + "Integrate the Mac experience", + "Navigation", + "Inputs", + "App icons", + "Layout", + "Menus", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Machine learning", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Planning your design", + "The role of machine learning in your app", + "Critical or complementary", + "Private or public", + "Proactive or reactive", + "Visible or invisible", + "Dynamic or static", + "Explicit feedback", + "Implicit feedback", + "Calibration", + "Corrections", + "Mistakes", + "Multiple options", + "Confidence", + "Attribution", + "Limitations", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Maps", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/maps", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Custom information", + "Place cards", + "Displaying place cards in a map", + "Adding place cards outside of a map", + "Indoor maps", + "Platform considerations", + "watchOS", + "Developer documentation", + "Change log" + ] + }, + { + "title": "NFC", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/nfc", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "In-app tag reading", + "Background tag reading", + "Platform considerations", + "Developer documentation" + ] + }, + { + "title": "Photo editing", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/photo-editing", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Developer documentation" + ] + }, + { + "title": "ResearchKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/researchkit", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Creating the onboarding experience", + "1. Introduction", + "2. Determine eligibility", + "3. Get informed consent", + "4. Request permission to access data", + "Conducting research", + "Managing personal information and providing encouragement", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "SharePlay", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/shareplay", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Sharing activities", + "Platform considerations", + "visionOS", + "Maintaining a shared context", + "Adjusting a shared context", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "ShazamKit", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/shazamkit", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Developer documentation" + ] + }, + { + "title": "Sign in with Apple", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Offering Sign in with Apple", + "Collecting data", + "Displaying buttons", + "Using the system-provided buttons", + "White", + "White with outline", + "Black", + "Button size and corner radius", + "Creating a custom Sign in with Apple button", + "Custom buttons with a logo and text", + "Custom logo-only buttons", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Siri", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Integrating your app with Siri", + "A closer look at intents", + "Provide information about actions and support suggestions", + "Design a great voice experience", + "Recognize that people use Siri in different contexts", + "System intents", + "Design responses to system intents", + "Enhance the voice experience for system intents", + "Design a custom interface for a system intent", + "Custom intents", + "Custom intent categories and responses", + "Design a custom intent", + "Help people customize their requests", + "Enhance the voice experience for custom intents", + "Shortcuts and suggestions", + "Make app actions widely available", + "Suggest Shortcuts people might want to add to Siri", + "Display shortcuts on the Siri watch face", + "Create shortcut titles and subtitles", + "Provide default phrases for shortcuts", + "Make shortcuts customizable", + "Editorial guidelines", + "Referring to Shortcuts", + "Referring to Apple products", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Tap to Pay on iPhone", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Enabling Tap to Pay on iPhone", + "Educating merchants", + "Checking out", + "Displaying results", + "Additional interactions", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Technologies", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/technologies", + "summary": "", + "platforms": [], + "sections": [] + }, + { + "title": "VoiceOver", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/voiceover", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Descriptions", + "Navigation", + "Platform considerations", + "visionOS", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "Wallet", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/wallet", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Passes", + "Designing passes", + "Pass styles", + "Boarding passes", + "Coupons", + "Store cards", + "Event tickets", + "Generic passes", + "Passes for Apple Watch", + "Order tracking", + "Displaying order and fulfillment details", + "Identity verification", + "Platform considerations", + "Pass image dimensions", + "Related", + "Developer documentation", + "Change log" + ] + }, + { + "title": "iCloud", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/icloud", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Platform considerations", + "Developer documentation", + "Change log" + ] + }, + { + "title": "iMessage apps and stickers", + "category": "technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/imessage-apps-and-stickers", + "summary": "", + "platforms": [], + "sections": [ + "Overview", + "Best practices", + "Icon sizes", + "Sticker sizes", + "Platform considerations", + "Related", + "Developer documentation", + "Change log" + ] + } + ] +} \ No newline at end of file diff --git a/data/categories/components.json b/data/categories/components.json new file mode 100644 index 0000000..2a7d9b5 --- /dev/null +++ b/data/categories/components.json @@ -0,0 +1,397 @@ +{ + "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": "components" + }, + "name": "Components", + "articles": [ + { + "title": "Components", + "url": "https://developer.apple.com/design/human-interface-guidelines/components", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Content", + "url": "/design/human-interface-guidelines/content" + }, + { + "title": "Layout and organization", + "url": "/design/human-interface-guidelines/layout-and-organization" + }, + { + "title": "Menus and actions", + "url": "/design/human-interface-guidelines/menus-and-actions" + }, + { + "title": "Navigation and search", + "url": "/design/human-interface-guidelines/navigation-and-search" + }, + { + "title": "Presentation", + "url": "/design/human-interface-guidelines/presentation" + }, + { + "title": "Selection and input", + "url": "/design/human-interface-guidelines/selection-and-input" + }, + { + "title": "Status", + "url": "/design/human-interface-guidelines/status" + }, + { + "title": "System experiences", + "url": "/design/human-interface-guidelines/system-experiences" + } + ], + "image_count": 0 + }, + { + "title": "Content", + "url": "https://developer.apple.com/design/human-interface-guidelines/content", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Charts", + "url": "/design/human-interface-guidelines/charts" + }, + { + "title": "Image views", + "url": "/design/human-interface-guidelines/image-views" + }, + { + "title": "Text views", + "url": "/design/human-interface-guidelines/text-views" + }, + { + "title": "Web views", + "url": "/design/human-interface-guidelines/web-views" + } + ], + "image_count": 0 + }, + { + "title": "Layout and organization", + "url": "https://developer.apple.com/design/human-interface-guidelines/layout-and-organization", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Boxes", + "url": "/design/human-interface-guidelines/boxes" + }, + { + "title": "Collections", + "url": "/design/human-interface-guidelines/collections" + }, + { + "title": "Column views", + "url": "/design/human-interface-guidelines/column-views" + }, + { + "title": "Disclosure controls", + "url": "/design/human-interface-guidelines/disclosure-controls" + }, + { + "title": "Labels", + "url": "/design/human-interface-guidelines/labels" + }, + { + "title": "Lists and tables", + "url": "/design/human-interface-guidelines/lists-and-tables" + }, + { + "title": "Lockups", + "url": "/design/human-interface-guidelines/lockups" + }, + { + "title": "Outline views", + "url": "/design/human-interface-guidelines/outline-views" + }, + { + "title": "Split views", + "url": "/design/human-interface-guidelines/split-views" + }, + { + "title": "Tab views", + "url": "/design/human-interface-guidelines/tab-views" + } + ], + "image_count": 0 + }, + { + "title": "Menus and actions", + "url": "https://developer.apple.com/design/human-interface-guidelines/menus-and-actions", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Activity views", + "url": "/design/human-interface-guidelines/activity-views" + }, + { + "title": "Buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "Context menus", + "url": "/design/human-interface-guidelines/context-menus" + }, + { + "title": "Dock menus", + "url": "/design/human-interface-guidelines/dock-menus" + }, + { + "title": "Edit menus", + "url": "/design/human-interface-guidelines/edit-menus" + }, + { + "title": "Home Screen quick actions", + "url": "/design/human-interface-guidelines/home-screen-quick-actions" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Ornaments", + "url": "/design/human-interface-guidelines/ornaments" + }, + { + "title": "Pop-up buttons", + "url": "/design/human-interface-guidelines/pop-up-buttons" + }, + { + "title": "Pull-down buttons", + "url": "/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "The menu bar", + "url": "/design/human-interface-guidelines/the-menu-bar" + }, + { + "title": "Toolbars", + "url": "/design/human-interface-guidelines/toolbars" + } + ], + "image_count": 0 + }, + { + "title": "Navigation and search", + "url": "https://developer.apple.com/design/human-interface-guidelines/navigation-and-search", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Path controls", + "url": "/design/human-interface-guidelines/path-controls" + }, + { + "title": "Search fields", + "url": "/design/human-interface-guidelines/search-fields" + }, + { + "title": "Sidebars", + "url": "/design/human-interface-guidelines/sidebars" + }, + { + "title": "Tab bars", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "Token fields", + "url": "/design/human-interface-guidelines/token-fields" + } + ], + "image_count": 0 + }, + { + "title": "Presentation", + "url": "https://developer.apple.com/design/human-interface-guidelines/presentation", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Action sheets", + "url": "/design/human-interface-guidelines/action-sheets" + }, + { + "title": "Alerts", + "url": "/design/human-interface-guidelines/alerts" + }, + { + "title": "Page controls", + "url": "/design/human-interface-guidelines/page-controls" + }, + { + "title": "Panels", + "url": "/design/human-interface-guidelines/panels" + }, + { + "title": "Popovers", + "url": "/design/human-interface-guidelines/popovers" + }, + { + "title": "Scroll views", + "url": "/design/human-interface-guidelines/scroll-views" + }, + { + "title": "Sheets", + "url": "/design/human-interface-guidelines/sheets" + }, + { + "title": "Windows", + "url": "/design/human-interface-guidelines/windows" + } + ], + "image_count": 0 + }, + { + "title": "Selection and input", + "url": "https://developer.apple.com/design/human-interface-guidelines/selection-and-input", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Color wells", + "url": "/design/human-interface-guidelines/color-wells" + }, + { + "title": "Combo boxes", + "url": "/design/human-interface-guidelines/combo-boxes" + }, + { + "title": "Digit entry views", + "url": "/design/human-interface-guidelines/digit-entry-views" + }, + { + "title": "Image wells", + "url": "/design/human-interface-guidelines/image-wells" + }, + { + "title": "Pickers", + "url": "/design/human-interface-guidelines/pickers" + }, + { + "title": "Segmented controls", + "url": "/design/human-interface-guidelines/segmented-controls" + }, + { + "title": "Sliders", + "url": "/design/human-interface-guidelines/sliders" + }, + { + "title": "Steppers", + "url": "/design/human-interface-guidelines/steppers" + }, + { + "title": "Text fields", + "url": "/design/human-interface-guidelines/text-fields" + }, + { + "title": "Toggles", + "url": "/design/human-interface-guidelines/toggles" + }, + { + "title": "Virtual keyboards", + "url": "/design/human-interface-guidelines/virtual-keyboards" + } + ], + "image_count": 0 + }, + { + "title": "Status", + "url": "https://developer.apple.com/design/human-interface-guidelines/status", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Activity rings", + "url": "/design/human-interface-guidelines/activity-rings" + }, + { + "title": "Gauges", + "url": "/design/human-interface-guidelines/gauges" + }, + { + "title": "Progress indicators", + "url": "/design/human-interface-guidelines/progress-indicators" + }, + { + "title": "Rating indicators", + "url": "/design/human-interface-guidelines/rating-indicators" + } + ], + "image_count": 0 + }, + { + "title": "System experiences", + "url": "https://developer.apple.com/design/human-interface-guidelines/system-experiences", + "category": "components", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "App Shortcuts", + "url": "/design/human-interface-guidelines/app-shortcuts" + }, + { + "title": "Complications", + "url": "/design/human-interface-guidelines/complications" + }, + { + "title": "Controls", + "url": "/design/human-interface-guidelines/controls" + }, + { + "title": "Live Activities", + "url": "/design/human-interface-guidelines/live-activities" + }, + { + "title": "Notifications", + "url": "/design/human-interface-guidelines/notifications" + }, + { + "title": "Status bars", + "url": "/design/human-interface-guidelines/status-bars" + }, + { + "title": "Top Shelf", + "url": "/design/human-interface-guidelines/top-shelf" + }, + { + "title": "Watch faces", + "url": "/design/human-interface-guidelines/watch-faces" + }, + { + "title": "Widgets", + "url": "/design/human-interface-guidelines/widgets" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/data/categories/foundations.json b/data/categories/foundations.json new file mode 100644 index 0000000..b5ac5f7 --- /dev/null +++ b/data/categories/foundations.json @@ -0,0 +1,17904 @@ +{ + "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 + } + ] +} \ No newline at end of file diff --git a/data/categories/general.json b/data/categories/general.json new file mode 100644 index 0000000..b57d8b3 --- /dev/null +++ b/data/categories/general.json @@ -0,0 +1,4137 @@ +{ + "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": "general" + }, + "name": "General", + "articles": [ + { + "title": "Activity views", + "url": "https://developer.apple.com/design/human-interface-guidelines/activity-views", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Activity views present sharing activities like messaging and actions like Copy and Print, in addition to quick access to frequently used apps. People typically reveal a share sheet by choosing an Action button while viewing a page or document, or after they’ve selected an item. An activity view can appear as a sheet or a popover, depending on the device and orientation." + }, + { + "type": "paragraph", + "text": "You can provide app-specific activities that can appear in a share sheet when people open it within your app or game. For example, Photos provides app-specific actions like Copy Photo, Add to Album, and Adjust Location. By default, the system lists app-specific actions before actions — such as Add to Files or AirPlay — that are available in multiple apps or throughout the system. People can edit the list of actions to ensure that it displays the ones they use most and to add new ones." + }, + { + "type": "paragraph", + "text": "You can also create app extensions to provide custom share and action activities that people can use in other apps. (An app extension is code you provide that people can install and use outside of your app.) For example, you might create a custom share activity that people can install to help them share a webpage with a specific social media service. Even though macOS doesn’t provide an activity view, you can create share and action app extensions that people can use on a Mac. For guidance, see Share and action extensions." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Avoid creating duplicate versions of common actions that are already available in the activity view. For example, providing a duplicate Print action is unnecessary and confusing because people wouldn’t know how to distinguish your action from the system-provided one. If you need to provide app-specific functionality that’s similar to an existing action, give it a custom title. For example, if you let people use custom formatting to print a bank transaction, use a title that helps people understand what your print activity does, like “Print Transaction.”" + }, + { + "type": "paragraph", + "text": "Consider using a symbol to represent your custom activity. SF Symbols provides a comprehensive set of configurable symbols you can use to communicate items and concepts in an activity view. If you need to create a custom interface icon, center it in an area measuring about 70x70 pixels. For guidance, see Icons." + }, + { + "type": "paragraph", + "text": "Write a succinct, descriptive title for each custom action you provide. If a title is too long, the system wraps it and may truncate it. Prefer a single verb or a brief verb phrase that clearly communicates what the action does. Avoid including your company or product name in an action title. In contrast, the share sheet displays the title of a share activity — typically a company name — below the icon that represents it." + }, + { + "type": "paragraph", + "text": "Make sure activities are appropriate for the current context. Although you can’t reorder system-provided tasks in an activity view, you can exclude tasks that aren’t applicable to your app. For example, if it doesn’t make sense to print from within your app, you can exclude the Print activity. You can also identify which custom tasks to show at any given time." + }, + { + "type": "paragraph", + "text": "Use the Share button to display an activity view. People are accustomed to accessing system-provided activities when they choose the Share button. Avoid confusing people by providing an alternative way to do the same thing." + } + ] + }, + { + "heading": "Share and action extensions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Share extensions give people a convenient way to share information from the current context with apps, social media accounts, and other services. Action extensions let people initiate content-specific tasks — like adding a bookmark, copying a link, editing an inline image, or displaying selected text in another language — without leaving the current context." + }, + { + "type": "paragraph", + "text": "The system presents share and action extensions differently depending on the platform:" + }, + { + "type": "list", + "items": [ + "In iOS and iPadOS, share and action extensions are displayed in the share sheet that appears when people choose an Action button.", + "In macOS, people access share extensions by clicking a Share button in the toolbar or choosing Share in a context menu. People can access an action extension by holding the pointer over certain types of embedded content — like an image they add to a Mail compose window — clicking a toolbar button, or choosing a quick action in a Finder window." + ] + }, + { + "type": "paragraph", + "text": "If necessary, create a custom interface that feels familiar to people. For a share extension, prefer the system-provided composition view because it provides a consistent sharing experience that people already know. For an action extension, include your app name. If you need to present an interface, include elements of your app’s interface to help people understand that your extension and your app are related." + }, + { + "type": "paragraph", + "text": "Streamline and limit interaction. People appreciate extensions that let them perform a task in just a few steps. For example, a share extension might immediately post an image to a social media account with a single tap or click." + }, + { + "type": "paragraph", + "text": "Avoid placing a modal view above your extension. By default, the system displays an extension within a modal view. While it might be necessary to display an alert above an extension, avoid displaying additional modal views." + }, + { + "type": "paragraph", + "text": "If necessary, provide an image that communicates the purpose of your extension. A share extension automatically uses your app icon, helping give people confidence that your app provided the extension. For an action extension, prefer using a symbol or creating an interface icon that clearly identifies the task." + }, + { + "type": "paragraph", + "text": "Use your main app to denote the progress of a lengthy operation. An activity view dismisses immediately after people complete the task in your share or action extension. If a task is time-consuming, continue it in the background, and give people a way to check the status in your main app. Although you can use a notification to tell people about a problem, don’t notify them simply because the task completes." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or visionOS. Not supported in macOS, tvOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Sheets" + }, + { + "type": "paragraph", + "text": "Popovers" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "UIActivityViewController — UIKit" + }, + { + "type": "paragraph", + "text": "UIActivity — UIKit" + }, + { + "type": "paragraph", + "text": "App Extension Support — Foundation" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Share and action extensions", + "url": "/design/human-interface-guidelines/activity-views#Share-and-action-extensions" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/activity-views#Best-practices" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Icons", + "url": "/design/human-interface-guidelines/icons" + }, + { + "title": "symbol", + "url": "https://developer.apple.com/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "icon", + "url": "https://developer.apple.com/design/human-interface-guidelines/icons" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/activity-views#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/activity-views#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/activity-views#Related" + }, + { + "title": "Sheets", + "url": "/design/human-interface-guidelines/sheets" + }, + { + "title": "Popovers", + "url": "/design/human-interface-guidelines/popovers" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/activity-views#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/activity-views#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Context menus", + "url": "https://developer.apple.com/design/human-interface-guidelines/context-menus", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Although a context menu provides convenient access to frequently used items, it’s hidden by default, so people might not know it’s there. To reveal a context menu, people generally choose a view or select some content and then perform an action, using the input modes their current configuration supports. For example:" + }, + { + "type": "list", + "items": [ + "The system-defined touch or pinch and hold gesture in visionOS, iOS, and iPadOS", + "Pressing the Control key while clicking a pointing device in macOS and iPadOS", + "Using a secondary click on a Magic Trackpad in macOS or iPadOS" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prioritize relevancy when choosing items to include in a context menu. A context menu isn’t for providing advanced or rarely used items; instead, it helps people quickly access the commands they’re most likely to need in their current context. For example, the context menu for a Mail message in the Inbox includes commands for replying and moving the message, but not commands for editing message content, managing mailboxes, or filtering messages." + }, + { + "type": "paragraph", + "text": "Aim for a small number of menu items. A context menu that’s too long can be difficult to scan and scroll." + }, + { + "type": "paragraph", + "text": "Support context menus consistently throughout your app. If you provide context menus for items in some places but not in others, people won’t know where they can use the feature and may think there’s a problem." + }, + { + "type": "paragraph", + "text": "Always make context menu items available in the main interface, too. For example, in Mail in iOS and iPadOS, the context menu items that are available for a message in the Inbox are also available in the toolbar of the message view. In macOS, an app’s menu bar menus list all the app’s commands, including those in various context menus." + }, + { + "type": "paragraph", + "text": "If you need to use submenus to manage a menu’s complexity, keep them to one level. A submenu is a menu item that reveals a secondary menu of logically related commands. Although submenus can shorten a context menu and clarify its commands, more than one level of submenu complicates the experience and can be difficult for people to navigate. If you need to include a submenu, give it an intuitive title that helps people predict its contents without opening it. For guidance, see Submenus." + }, + { + "type": "paragraph", + "text": "Hide unavailable menu items, don’t dim them. Unlike a regular menu, which helps people discover actions they can perform even when the action isn’t available, a context menu displays only the actions that are relevant to the currently selected view or content. In macOS, the exceptions are the Cut, Copy, and Paste menu items, which may appear unavailable if they don’t apply to the current context." + }, + { + "type": "paragraph", + "text": "Aim to place the most frequently used menu items where people are likely to encounter them first. When a context menu opens, people often read it starting from the part that’s closest to where their finger or pointer revealed it. Depending on the location of the selected content, a context menu might open above or below it, so you might also need to reverse the order of items to match the position of the menu." + }, + { + "type": "paragraph", + "text": "Show keyboard shortcuts in your app’s main menus, not in context menus. Context menus already provide a shortcut to task-specific commands, so it’s redundant to display keyboard shortcuts too." + }, + { + "type": "paragraph", + "text": "Follow best practices for using separators. As with other types of menus, you can use separators to group items in a context menu and help people scan the menu more quickly. In general, you don’t want more than about three groups in a context menu. For guidance, see Menus." + }, + { + "type": "paragraph", + "text": "In iOS, iPadOS, and visionOS, warn people about context menu items that can destroy data. If you need to include potentially destructive items in your context menu — such as Delete or Remove — list them at the end of the menu and identify them as destructive (for developer guidance, see destructive). The system can display a destructive menu item using a red text color." + } + ] + }, + { + "heading": "Content", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A context menu seldom displays a title. In contrast, each item in a context menu needs to display a short label that clearly describes what it does. For guidance, see Menus > Labels." + }, + { + "type": "paragraph", + "text": "Include a title in a context menu only if doing so clarifies the menu’s effect. For example, when people select multiple Mail messages and tap the Mark toolbar button in iOS and iPadOS, the resulting context menu displays a title that states the number of selected messages, reminding people that the command they choose affects all the messages they selected." + }, + { + "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. For additional guidance, see Menus." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for tvOS. Not supported in watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Provide either a context menu or an edit menu for an item, but not both. If you provide both features for the same item, it can be confusing to people — and difficult for the system to detect their intent. See Edit menus." + }, + { + "type": "paragraph", + "text": "In iPadOS, consider using a context menu to let people create a new object in your app. iPadOS lets you reveal a context menu when people perform a long press on the touchscreen or use a secondary click with an attached trackpad or keyboard. For example, Files lets people create a new folder by revealing a context menu in an area between existing files and folders." + }, + { + "type": "paragraph", + "text": "In iOS and iPadOS, a context menu can display a preview of the current content near the list of commands. People can choose a command in the menu or — in some cases — they can tap the preview to open it or drag it to another area." + }, + { + "type": "paragraph", + "text": "Prefer a graphical preview that clarifies the target of a context menu’s commands. For example, when people reveal a context menu on a list item in Notes or Mail, the preview shows a condensed version of the actual content to help people confirm that they’re working with the item they intend." + }, + { + "type": "paragraph", + "text": "Ensure that your preview looks good as it animates. As people reveal a context menu on an onscreen object, the system animates the preview image as it emerges from the content, dimming the screen behind the preview and the menu. It’s important to adjust the preview’s clipping path to match the shape of the preview image so that its contours, such as the rounded corners, don’t appear to change during animation. For developer guidance, see UIContextMenuInteractionDelegate." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On a Mac, a context menu is sometimes called a contextual menu." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider using a context menu instead of a panel or inspector window to present frequently used functionality. Minimizing the number of separate views or windows your app opens can help people keep their space uncluttered." + }, + { + "type": "paragraph", + "text": "In general, avoid letting a context menu’s height exceed the height of the window. In visionOS, a window includes system-provided components above and below its top and bottom edges, such as window-management controls and the Share menu, so a context menu that’s too tall could obscure them. As you consider the number of items to include, be guided by the ways people are likely to use your app. For example, people who use an app to accomplish in-depth, specialist tasks often expect to spend time learning a large number of sophisticated commands and might appreciate contextual access to them. On the other hand, people who use an app to perform a few simple actions may appreciate short contextual menus that are quick to scan and use." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Menus" + }, + { + "type": "paragraph", + "text": "Edit menus" + }, + { + "type": "paragraph", + "text": "Pop-up buttons" + }, + { + "type": "paragraph", + "text": "Pull-down buttons" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "contextMenu(menuItems:) — SwiftUI" + }, + { + "type": "paragraph", + "text": "UIContextMenuInteraction — UIKit" + }, + { + "type": "paragraph", + "text": "popUpContextMenu(_:with:for:) — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Added guidance on hiding unavailable menu items." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "September 14, 2022", + "Refined guidance on including a submenu and added a guideline on using a context menu to support object creation in an iPadOS app." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/context-menus#Best-practices" + }, + { + "title": "Submenus", + "url": "/design/human-interface-guidelines/menus#Submenus" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Content", + "url": "/design/human-interface-guidelines/context-menus#Content" + }, + { + "title": "Menus > Labels", + "url": "https://developer.apple.com/design/human-interface-guidelines/menus#Labels" + }, + { + "title": "Standard icons", + "url": "/design/human-interface-guidelines/icons#Standard-icons" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/context-menus#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/context-menus#iOS-iPadOS" + }, + { + "title": "Edit menus", + "url": "/design/human-interface-guidelines/edit-menus" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/context-menus#macOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/context-menus#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/context-menus#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/context-menus#Related" + }, + { + "title": "Pop-up buttons", + "url": "/design/human-interface-guidelines/pop-up-buttons" + }, + { + "title": "Pull-down buttons", + "url": "/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/context-menus#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/context-menus#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Dock menus", + "url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The system-provided Dock menu items can vary depending on whether the app is open. For example, the Dock menu for Safari includes menu items for actions like viewing a current window or creating a new window." + }, + { + "type": "note", + "text": "NoteAlthough iOS and iPadOS don’t support a Dock menu, people can reveal a similar menu of system-provided and custom items — called Home Screen quick actions — when they long press an app icon on the Home Screen or in the Dock. For guidance, see Home Screen quick actions." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As with all menus, you need to label Dock menu items succinctly and organize them logically. For guidance, see Menus." + }, + { + "type": "paragraph", + "text": "Make custom Dock menu items available in other places, too. Not everyone uses a Dock menu, so it’s important to offer the same commands elsewhere, like in your menu bar menus or within your interface." + }, + { + "type": "paragraph", + "text": "Prefer high-value custom items for your Dock menu. For example, a Dock menu can list all currently or recently open windows, making it a convenient way to jump to the window people want. Also consider listing a few of the actions that are most likely to be useful when your app isn’t frontmost or when there are no open windows. For example, Mail includes items for getting new mail and composing a new message in addition to listing all open windows." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Menus" + }, + { + "type": "paragraph", + "text": "Home Screen quick actions" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "applicationDockMenu(_:) — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Home Screen quick actions", + "url": "/design/human-interface-guidelines/home-screen-quick-actions" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/dock-menus#Best-practices" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/dock-menus#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/dock-menus#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/dock-menus#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/dock-menus#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Edit menus", + "url": "https://developer.apple.com/design/human-interface-guidelines/edit-menus", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In addition to text, an edit menu’s commands can apply to many types of selectable content, such as images, files, and objects like contact cards, charts, or map locations. In iOS, iPadOS, and visionOS, the system automatically detects the data type of a selected item, which can result in the addition of a related action to the edit menu. For example, selecting an address can add an item like Get directions to the edit menu." + }, + { + "type": "paragraph", + "text": "Edit menus can look and behave slightly differently in different platforms." + }, + { + "type": "list", + "items": [ + "In iOS, the edit menu displays commands in a compact, horizontal list that appears when people touch and hold or double-tap to select content in a view. People can tap a chevron on the trailing edge to expand it into a context menu.", + "In iPadOS, the edit menu looks different depending on how people reveal it. When people use touch interactions to reveal the menu, it uses the compact, horizontal appearance. In contrast, when people use a keyboard or pointing device to reveal it, the edit menu opens directly in a context menu.", + "In macOS, people can access editing commands in a context menu they can reveal while in an editing task, as well as through the app’s Edit menu in the menu bar.", + "In visionOS, people use the standard pinch and hold gesture to open the edit menu as a horizontal bar, or they can open it in a context menu." + ] + }, + { + "type": "paragraph", + "text": "Editing content is rare in tvOS and watchOS experiences, so the system doesn’t provide an edit menu in these platforms." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer the system-provided edit menu. People are familiar with the contents and behavior of the system-provided component, so creating a custom menu that presents the same commands is redundant and likely to be confusing. For a list of standard edit menu commands, see UIResponderStandardEditActions." + }, + { + "type": "paragraph", + "text": "Let people reveal an edit menu using the system-defined interactions they already know. For example, people expect to touch and hold on a touchscreen, pinch and hold in visionOS, or use a secondary click with an attached trackpad or keyboard. Although the interactions to reveal an edit menu can differ based on platform, people don’t appreciate having to learn a custom interaction to perform a standard task." + }, + { + "type": "paragraph", + "text": "Offer commands that are relevant in the current context, removing or dimming commands that don’t apply. For example, if nothing is selected, avoid showing options that require a selection, such as Copy or Cut. Similarly, avoid showing a Paste option when there’s nothing to paste." + }, + { + "type": "paragraph", + "text": "List custom commands near relevant system-provided ones. For example, if you offer custom formatting commands, you can help maintain the ordering people expect by listing them after the system-provided commands in the format section. Avoid overwhelming people with too many custom commands." + }, + { + "type": "paragraph", + "text": "When it makes sense, let people select and copy noneditable text. People appreciate being able to paste static content — such as an image caption or social media status — into a message, note, or web search. In general, let people copy content text, but not control labels." + }, + { + "type": "paragraph", + "text": "Support undo and redo when possible. Like all menus, an edit menu doesn’t require confirmation before performing its actions, so people can easily use undo and redo to recover a previous state. For guidance, see Undo and redo." + }, + { + "type": "paragraph", + "text": "In general, avoid implementing other controls that perform the same functions as edit menu items. People typically expect to choose familiar edit commands in an edit menu, or use standard keyboard shortcuts. Offering redundant controls can crowd your interface, giving you less space for presenting actions that people might not already know about." + }, + { + "type": "paragraph", + "text": "Differentiate different types of deletion commands when necessary. For example, a Delete menu item behaves the same as pressing a Delete key, but a Cut menu item copies the selected content to the system pasteboard before deleting it." + } + ] + }, + { + "heading": "Content", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Create short labels for custom commands. Use verbs or short verb phrases that succinctly describe the action your command performs. For guidance, see Labels." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Ensure your edit menu works well in both styles. The system displays the compact, horizontal style when people use Multi-Touch gestures to reveal the edit menu, and the vertical style when people use a keyboard or pointing device to reveal it. For guidance using the vertical menu layout, see Menus > iOS, iPadOS." + }, + { + "type": "paragraph", + "text": "Adjust an edit menu’s placement, if necessary. Depending on available space, the default menu position is above or below the insertion point or selection. The system also displays a visual indicator that points to the targeted content. Although you can’t change the shape of the menu or its pointer, you can change the menu’s position. For example, you might need to move the menu to prevent it from covering important content or parts of your interface." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "To learn about the order of items in a macOS app’s Edit menu, see Edit menu." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Menus" + }, + { + "type": "paragraph", + "text": "Context menus" + }, + { + "type": "paragraph", + "text": "The menu bar" + }, + { + "type": "paragraph", + "text": "Undo and redo" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "UIEditMenuInteraction — UIKit" + }, + { + "type": "paragraph", + "text": "NSMenu — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "September 14, 2022", + "Added guidance on supporting both edit-menu styles in iPadOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "context menu", + "url": "/design/human-interface-guidelines/context-menus" + }, + { + "title": "Edit menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Edit-menu" + }, + { + "title": "pinch and hold", + "url": "/design/human-interface-guidelines/gestures#Standard-gestures" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/edit-menus#Best-practices" + }, + { + "title": "Undo and redo", + "url": "/design/human-interface-guidelines/undo-and-redo" + }, + { + "title": "Content", + "url": "/design/human-interface-guidelines/edit-menus#Content" + }, + { + "title": "Labels", + "url": "/design/human-interface-guidelines/labels" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/edit-menus#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/edit-menus#iOS-iPadOS" + }, + { + "title": "Menus > iOS, iPadOS", + "url": "/design/human-interface-guidelines/menus#iOS-iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/edit-menus#macOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/edit-menus#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/edit-menus#Related" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "The menu bar", + "url": "/design/human-interface-guidelines/the-menu-bar" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/edit-menus#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/edit-menus#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Home Screen quick actions", + "url": "https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People can get a menu of available quick actions when they touch and hold an app icon (on a 3D Touch device, people can press on the icon with increased pressure to see the menu). For example, Mail includes quick actions that open the Inbox or the VIP mailbox, initiate a search, and create a new message. In addition to app-specific actions, a Home Screen quick action menu also lists items for removing the app and editing the Home Screen." + }, + { + "type": "paragraph", + "text": "Each Home Screen quick action includes a title, an interface icon on the left or right (depending on your app’s position on the Home Screen), and an optional subtitle. The title and subtitle are always left-aligned in left-to-right languages. Your app can even dynamically update its quick actions when new information is available. For example, Messages provides quick actions for opening your most recent conversations." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Create quick actions for compelling, high-value tasks. For example, Maps lets people search near their current location or get directions home without first opening the Maps app. People tend to expect every app to provide at least one useful quick action; you can provide a total of four." + }, + { + "type": "paragraph", + "text": "Avoid making unpredictable changes to quick actions. Dynamic quick actions are a great way to keep actions relevant. For example, it may make sense to update quick actions based on the current location or recent activities in your app, time of day, or changes in settings. Make sure that actions change in ways that people can predict." + }, + { + "type": "paragraph", + "text": "For each quick action, provide a succinct title that instantly communicates the results of the action. For example, titles like “Directions Home,” “Create New Contact,” and “New Message” can help people understand what happens when they choose the action. If you need to give more context, provide a subtitle too. Mail uses subtitles to indicate whether there are unread messages in the Inbox and VIP folder. Don’t include your app name or any extraneous information in the title or subtitle, keep the text short to avoid truncation, and take localization into account as you write the text." + }, + { + "type": "paragraph", + "text": "Provide a familiar interface icon for each quick action. Prefer using SF Symbols to represent actions. For a list of icons that represent common actions, see Standard icons; for additional guidance, see Menus." + }, + { + "type": "paragraph", + "text": "If you design your own interface icon, use the Quick Action Icon Template that’s included with Apple Design Resources for iOS and iPadOS." + }, + { + "type": "paragraph", + "text": "Don’t use an emoji in place of a symbol or interface icon. Emojis are full color, whereas quick action symbols are monochromatic and change appearance in Dark Mode to maintain contrast." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Menus" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Add Home Screen quick actions — UIKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/home-screen-quick-actions#Best-practices" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Standard icons", + "url": "/design/human-interface-guidelines/icons#Standard-icons" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/home-screen-quick-actions#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/home-screen-quick-actions#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/home-screen-quick-actions#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/home-screen-quick-actions#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Panels", + "url": "https://developer.apple.com/design/human-interface-guidelines/panels", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In general, a panel has a less prominent appearance than an app’s main window. When the situation calls for it, a panel can also use a dark, translucent style to support a heads-up display (or HUD) experience." + }, + { + "type": "paragraph", + "text": "When your app runs in other platforms, consider using a modal view to present supplementary content that’s relevant to the current task or selection. For guidance, see Modality." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a panel to give people quick access to important controls or information related to the content they’re working with. For example, you might use a panel to provide controls or settings that affect the selected item in the active document or window." + }, + { + "type": "paragraph", + "text": "Consider using a panel to present inspector functionality. An inspector displays the details of the currently selected item, automatically updating its contents when the item changes or when people select a new item. In contrast, if you need to present an Info window — which always maintains the same contents, even when the selected item changes — use a regular window, not a panel. Depending on the layout of your app, you might also consider using a split view pane to present an inspector." + }, + { + "type": "paragraph", + "text": "Prefer simple adjustment controls in a panel. As much as possible, avoid including controls that require typing text or selecting items to act upon because these actions can require multiple steps. Instead, consider using controls like sliders and steppers because these components can give people more direct control." + }, + { + "type": "paragraph", + "text": "Write a brief title that describes the panel’s purpose. Because a panel often floats above other open windows in your app, it needs a title bar so people can position it where they want. Create a short title using a noun — or a noun phrase with title-style capitalization — that can help people recognize the panel onscreen. For example, macOS provides familiar panels titled “Fonts” and “Colors,” and many apps use the title “Inspector.”" + }, + { + "type": "paragraph", + "text": "Show and hide panels appropriately. When your app becomes active, bring all of its open panels to the front, regardless of which window was active when the panel opened. When your app is inactive, hide all of its panels." + }, + { + "type": "paragraph", + "text": "Avoid including panels in the Window menu’s documents list. It’s fine to include commands for showing or hiding panels in the Window menu, but panels aren’t documents or standard app windows, and they don’t belong in the Window menu’s list." + }, + { + "type": "paragraph", + "text": "In general, avoid making a panel’s minimize button available. People don’t usually need to minimize a panel, because it displays only when needed and disappears when the app is inactive." + }, + { + "type": "paragraph", + "text": "Refer to panels by title in your interface and in help documentation. In menus, use the panel’s title without including the term panel: for example, “Show Fonts,” “Show Colors,” and “Show Inspector.” In help documentation, it can be confusing to introduce “panel” as a different type of window, so it’s generally best to refer to a panel by its title or — when it adds clarity — by appending window to the title. For example, the title “Inspector” often supplies enough context to stand on its own, whereas it can be clearer to use “Fonts window” and “Colors window” instead of just “Fonts” and “Colors.”" + } + ] + }, + { + "heading": "HUD-style panels", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A HUD-style panel serves the same function as a standard panel, but its appearance is darker and translucent. HUDs work well in apps that present highly visual content or that provide an immersive experience, such as media editing or a full-screen slide show. For example, QuickTime Player uses a HUD to display inspector information without obstructing too much content." + }, + { + "type": "paragraph", + "text": "Prefer standard panels. People can be distracted or confused by a HUD when there’s no logical reason for its presence. Also, a HUD might not match the current appearance setting. In general, use a HUD only:" + }, + { + "type": "list", + "items": [ + "In a media-oriented app that presents movies, photos, or slides", + "When a standard panel would obscure essential content", + "When you don’t need to include controls — with the exception of the disclosure triangle, most system-provided controls don’t match a HUD’s appearance." + ] + }, + { + "type": "paragraph", + "text": "Maintain one panel style when your app switches modes. For example, if you use a HUD when your app is in full-screen mode, prefer maintaining the HUD style when people take your app out of full-screen mode." + }, + { + "type": "paragraph", + "text": "Use color sparingly in HUDs. Too much color in the dark appearance of a HUD can be distracting. Often, you need only small amounts of high-contrast color to highlight important information in a HUD." + }, + { + "type": "paragraph", + "text": "Keep HUDs small. HUDs are designed to be unobtrusively useful, so letting them grow too large defeats their primary purpose. Don’t let a HUD obscure the content it adjusts, and make sure it doesn’t compete with the content for people’s attention." + }, + { + "type": "paragraph", + "text": "For developer guidance, see hudWindow." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Windows" + }, + { + "type": "paragraph", + "text": "Modality" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "NSPanel — AppKit" + }, + { + "type": "paragraph", + "text": "hudWindow — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "main window", + "url": "/design/human-interface-guidelines/windows#macOS-window-states" + }, + { + "title": "Modality", + "url": "/design/human-interface-guidelines/modality" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/panels#Best-practices" + }, + { + "title": "split view", + "url": "/design/human-interface-guidelines/split-views" + }, + { + "title": "Window menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Window-menu" + }, + { + "title": "HUD-style panels", + "url": "/design/human-interface-guidelines/panels#HUD-style-panels" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/panels#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/panels#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/panels#Related" + }, + { + "title": "Windows", + "url": "/design/human-interface-guidelines/windows" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/panels#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Path controls", + "url": "https://developer.apple.com/design/human-interface-guidelines/path-controls", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "For example, choosing View > Show Path Bar in the Finder displays a path bar at the bottom of the window. It shows the path of the selected item, or the path of the window’s folder if nothing is selected." + }, + { + "type": "paragraph", + "text": "There are two styles of path control." + }, + { + "type": "paragraph", + "text": "Standard. A linear list that includes the root disk, parent folders, and selected item. Each item appears with an icon and a name. If the list is too long to fit within the control, it hides names between the first and last items. If you make the control editable, people can drag an item onto the control to select the item and display its path in the control." + }, + { + "type": "paragraph", + "text": "Pop up. A control similar to a pop-up button that shows the icon and name of the selected item. People can click the item to open a menu containing the root disk, parent folders, and selected item. If you make the control editable, the menu contains an additional Choose command that people can use to select an item and display it in the control. They can also drag an item onto the control to select it and display its path." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a path control in the window body, not the window frame. Path controls aren’t intended for use in toolbars or status bars. Note that the path control in the Finder appears at the bottom of the window body, not in the status bar." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "File management" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "NSPathControl — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "pop-up button", + "url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/path-controls#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/path-controls#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/path-controls#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/path-controls#Related" + }, + { + "title": "File management", + "url": "/design/human-interface-guidelines/file-management" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/path-controls#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Pop-up buttons", + "url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "After people choose an item from a pop-up button’s menu, the menu closes, and the button can update its content to indicate the current selection." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a pop-up button to present a flat list of mutually exclusive options or states. A pop-up button helps people make a choice that affects their content or the surrounding view. Use a pull-down button instead if you need to:" + }, + { + "type": "list", + "items": [ + "Offer a list of actions", + "Let people select multiple items", + "Include a submenu" + ] + }, + { + "type": "paragraph", + "text": "Provide a useful default selection. A pop-up button can update its content to identify the current selection, but if people haven’t made a selection yet, it shows the default item you specify. When possible, make the default selection an item that most people are likely to want." + }, + { + "type": "paragraph", + "text": "Give people a way to predict a pop-up button’s options without opening it. For example, you can use an introductory label or a button label that describes the button’s effect, giving context to the options." + }, + { + "type": "paragraph", + "text": "Consider using a pop-up button when space is limited and you don’t need to display all options all the time. Pop-up buttons are a space-efficient way to present a wide array of choices." + }, + { + "type": "paragraph", + "text": "If necessary, include a Custom option in a pop-up button’s menu to provide additional items that are useful in some situations. Offering a Custom option can help you avoid cluttering the interface with items or controls that people need only occasionally. You can also display explanatory text below the list to help people understand how the options work." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, macOS, or visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Within a popover or modal view, consider using a pop-up button instead of a disclosure indicator to present multiple options for a list item. For example, people can quickly choose an option from the pop-up button’s menu without navigating to a detail view. Consider using a pop-up button in this scenario when you have a fairly small, well-defined set of options that work well in a menu." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Pull-down buttons" + }, + { + "type": "paragraph", + "text": "Buttons" + }, + { + "type": "paragraph", + "text": "Menus" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "MenuPickerStyle — SwiftUI" + }, + { + "type": "paragraph", + "text": "changesSelectionAsPrimaryAction — UIKit" + }, + { + "type": "paragraph", + "text": "NSPopUpButton — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "October 24, 2023", + "Added artwork." + ], + [ + "September 14, 2022", + "Added a guideline on using a pop-up button in a popover or modal view in iPadOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/pop-up-buttons#Best-practices" + }, + { + "title": "pull-down button", + "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/pop-up-buttons#Platform-considerations" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/pop-up-buttons#iPadOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/pop-up-buttons#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/pop-up-buttons#Related" + }, + { + "title": "Pull-down buttons", + "url": "/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "Buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/pop-up-buttons#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/pop-up-buttons#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Popovers", + "url": "https://developer.apple.com/design/human-interface-guidelines/popovers", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a popover to expose a small amount of information or functionality. Because a popover disappears after people interact with it, limit the amount of functionality in the popover to a few related tasks. For example, a calendar event popover makes it easy for people to change the date or time of an event, or to move it to another calendar. The popover disappears after the change, letting people continue reviewing the events on their calendar." + }, + { + "type": "paragraph", + "text": "Consider using popovers when you want more room for content. Views like sidebars and panels take up a lot of space. If you need content only temporarily, displaying it in a popover can help streamline your interface." + }, + { + "type": "paragraph", + "text": "Position popovers appropriately. Make sure a popover’s arrow points as directly as possible to the element that revealed it. Ideally, a popover doesn’t cover the element that revealed it or any essential content people may need to see while using it." + }, + { + "type": "paragraph", + "text": "Use a Close button for confirmation and guidance only. A Close button, including Cancel or Done, is worth including if it provides clarity, like exiting with or without saving changes. Otherwise, a popover generally closes when people click or tap outside its bounds or select an item in the popover. If multiple selections are possible, make sure the popover remains open until people explicitly dismiss it or they click or tap outside its bounds." + }, + { + "type": "paragraph", + "text": "Always save work when automatically closing a nonmodal popover. People can unintentionally dismiss a nonmodal popover by clicking or tapping outside its bounds. Discard people’s work only when they click or tap an explicit Cancel button." + }, + { + "type": "paragraph", + "text": "Show one popover at a time. Displaying multiple popovers clutters the interface and causes confusion. Never show a cascade or hierarchy of popovers, in which one emerges from another. If you need to show a new popover, close the open one first." + }, + { + "type": "paragraph", + "text": "Don’t show another view over a popover. Make sure nothing displays on top of a popover, except for an alert." + }, + { + "type": "paragraph", + "text": "When possible, let people close one popover and open another with a single click or tap. Avoiding extra gestures is especially desirable when several different bar buttons each open a popover." + }, + { + "type": "paragraph", + "text": "Avoid making a popover too big. Make a popover only big enough to display its contents and point to the place it came from. If necessary, the system can adjust the size of a popover to ensure it fits well in the interface." + }, + { + "type": "paragraph", + "text": "Provide a smooth transition when changing the size of a popover. Some popovers provide both condensed and expanded views of the same information. If you adjust the size of a popover, animate the change to avoid giving the impression that a new popover replaced the old one." + }, + { + "type": "paragraph", + "text": "Avoid using the word popover in help documentation. Instead, refer to a specific task or selection. For example, instead of “Select the Show button at the bottom of the popover,” you might write “Select the Show button.”" + }, + { + "type": "paragraph", + "text": "Avoid using a popover to show a warning. People can miss a popover or accidentally close it. If you need to warn people, use an alert instead." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Avoid displaying popovers in compact views. Make your app or game dynamically adjust its layout based on the size class of the content area. Reserve popovers for wide views; for compact views, use all available screen space by presenting information in a full-screen modal view like a sheet instead. For related guidance, see Modality." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "You can make a popover detachable in macOS, which becomes a separate panel when people drag it. The panel remains visible onscreen while people interact with other content." + }, + { + "type": "paragraph", + "text": "Consider letting people detach a popover. People might appreciate being able to convert a popover into a panel if they want to view other information while the popover remains visible." + }, + { + "type": "paragraph", + "text": "Make minimal appearance changes to a detached popover. A panel that looks similar to the original popover helps people maintain context." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Sheets" + }, + { + "type": "paragraph", + "text": "Action sheets" + }, + { + "type": "paragraph", + "text": "Alerts" + }, + { + "type": "paragraph", + "text": "Modality" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "popover(isPresented:attachmentAnchor:arrowEdge:content:) — SwiftUI" + }, + { + "type": "paragraph", + "text": "UIPopoverPresentationController — UIKit" + }, + { + "type": "paragraph", + "text": "NSPopover — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/popovers#Best-practices" + }, + { + "title": "alert", + "url": "/design/human-interface-guidelines/alerts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/popovers#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/popovers#iOS-iPadOS" + }, + { + "title": "Modality", + "url": "/design/human-interface-guidelines/modality" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/popovers#macOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/popovers#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/popovers#Related" + }, + { + "title": "Sheets", + "url": "/design/human-interface-guidelines/sheets" + }, + { + "title": "Action sheets", + "url": "/design/human-interface-guidelines/action-sheets" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/popovers#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Pull-down buttons", + "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "After people choose an item in a pull-down button’s menu, the menu closes, and the app performs the chosen action." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a pull-down button to present commands or items that are directly related to the button’s action. The menu lets you help people clarify the button’s target or customize its behavior without requiring additional buttons in your interface. For example:" + }, + { + "type": "list", + "items": [ + "An Add button could present a menu that lets people specify the item they want to add.", + "A Sort button could use a menu to let people select an attribute on which to sort.", + "A Back button could let people choose a specific location to revisit instead of opening the previous one." + ] + }, + { + "type": "paragraph", + "text": "If you need to provide a list of mutually exclusive choices that aren’t commands, use a pop-up button instead." + }, + { + "type": "paragraph", + "text": "Avoid putting all of a view’s actions in one pull-down button. A view’s primary actions need to be easily discoverable, so you don’t want to hide them in a pull-down button that people have to open before they can do anything." + }, + { + "type": "paragraph", + "text": "Balance menu length with ease of use. Because people have to interact with a pull-down button before they can view its menu, listing a minimum of three items can help the interaction feel worthwhile. If you need to list only one or two items, consider using alternative components to present them, such as buttons to perform actions and toggles or switches to present selections. In contrast, listing too many items in a pull-down button’s menu can slow people down because it takes longer to find a specific item." + }, + { + "type": "paragraph", + "text": "Display a succinct menu title only if it adds meaning. In general, a pull-down button’s content — combined with descriptive menu items — provides all the context people need, making a menu title unnecessary." + }, + { + "type": "paragraph", + "text": "Let people know when a pull-down button’s menu item is destructive, and ask them to confirm their intent. Menus use red text to highlight actions that you identify as potentially destructive. When people choose a destructive action, the system displays an action sheet (iOS) or popover (iPadOS) in which they can confirm their choice or cancel the action. Because an action sheet appears in a different location from the menu and requires deliberate dismissal, it can help people avoid losing data by mistake." + }, + { + "type": "paragraph", + "text": "Include an interface icon with a menu item when it provides value. If you need to clarify an item’s meaning, you can display an icon or image after its label. Using SF Symbols for this purpose can help you provide a familiar experience while ensuring that the symbol remains aligned with the text at every scale." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for macOS or visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "note", + "text": "NoteYou can also let people reveal a pull-down menu by performing a specific gesture on a button. For example, in iOS 14 and later, Safari responds to a touch and hold gesture on the Tabs button by displaying a menu of tab-related actions, like New Tab and Close All Tabs." + }, + { + "type": "paragraph", + "text": "Consider using a More pull-down button to present items that don’t need prominent positions in the main interface. A More button can help you offer a range of items where space is constrained, but it can also hinder discoverability. Although people generally understand that a More button offers additional functionality related to the current context, the ellipsis icon doesn’t necessarily help them predict its contents. To design an effective More button, weigh the convenience of its size against its impact on discoverability to find a balance that works in your app." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Pop-up buttons" + }, + { + "type": "paragraph", + "text": "Buttons" + }, + { + "type": "paragraph", + "text": "Menus" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "MenuPickerStyle — SwiftUI" + }, + { + "type": "paragraph", + "text": "showsMenuAsPrimaryAction — UIKit" + }, + { + "type": "paragraph", + "text": "pullsDown — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 14, 2022", + "Refined guidance on designing a useful menu length." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/pull-down-buttons#Best-practices" + }, + { + "title": "pop-up button", + "url": "/design/human-interface-guidelines/pop-up-buttons" + }, + { + "title": "action sheet", + "url": "/design/human-interface-guidelines/action-sheets" + }, + { + "title": "popover", + "url": "/design/human-interface-guidelines/popovers" + }, + { + "title": "icon", + "url": "/design/human-interface-guidelines/icons" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/pull-down-buttons#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/pull-down-buttons#iOS-iPadOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/pull-down-buttons#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/pull-down-buttons#Related" + }, + { + "title": "Buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/pull-down-buttons#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/pull-down-buttons#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Search fields", + "url": "https://developer.apple.com/design/human-interface-guidelines/search-fields", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A search field is an editable text field that displays a Search icon, a Clear button, and placeholder text where people can enter what they are searching for. Search fields can use a scope control as well as tokens to help filter and refine the scope of their search. Across each platform, there are different patterns for accessing search based on the goals and design of your app." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Adding a search interface to your app; for guidance related to systemwide search, see Searching." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Display placeholder text that describes the type of information people can search for. For example, the Apple TV app includes the placeholder text Shows, Movies, and More. Avoid using a term like Search for placeholder text because it doesn’t provide any helpful information." + }, + { + "type": "paragraph", + "text": "If possible, start search immediately when a person types. Searching while someone types makes the search experience feel more responsive because it provides results that are continuously refined as the text becomes more specific." + }, + { + "type": "paragraph", + "text": "Consider showing suggested search terms before search begins, or as a person types. This can help someone search faster by suggesting common searches, even when the search itself doesn’t begin immediately." + }, + { + "type": "paragraph", + "text": "Simplify search results. Provide the most relevant search results first to minimize the need for someone to scroll to find what they’re looking for. In addition to prioritizing the most likely results, consider categorizing them to help people find what they want." + }, + { + "type": "paragraph", + "text": "Consider letting people filter search results. For example, you can include a scope control in the search results content area to help people quickly and easily filter search results." + } + ] + }, + { + "heading": "Scope controls and tokens", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Scope controls and tokens are components you can use to let someone narrow the parameters of a search either before or after they make it." + }, + { + "type": "list", + "items": [ + "A scope control acts like a segmented control for choosing a category for the search.", + "A token is a visual representation of a search term that someone can select and edit, and acts as a filter for any additional terms in the search." + ] + }, + { + "type": "paragraph", + "text": "Use a scope control to filter among clearly defined search categories. A scope control can help someone move from a broader scope to a narrower one. For example, in Mail on iPhone, a scope control helps people move from searching their entire mailbox to just the specific mailbox they’re viewing. For developer guidance, see Scoping a search operation." + }, + { + "type": "paragraph", + "text": "Default to a broader scope and let people refine it as they need. A broader scope provides context for the full set of available results, which helps guide people in a useful direction when they choose to narrow the scope." + }, + { + "type": "paragraph", + "text": "Use tokens to filter by common search terms or items. When you define a token, the term it represents gains a visual treatment that encapsulates it, indicating that people can select and edit it as a single item. Tokens can clarify a search term, like filtering by a specific contact in Mail, or focus a search to a specific set of attributes, like filtering by photos in Messages. For the related macOS component, see Token fields." + }, + { + "type": "paragraph", + "text": "Consider pairing tokens with search suggestions. People may not know which tokens are available, so pairing them with search suggestions can help people learn how to use them." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for visionOS." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "There are three main places you can position the entry point for search:" + }, + { + "type": "list", + "items": [ + "In a tab bar at the bottom of the screen", + "In a toolbar at the bottom or top of the screen", + "Directly inline with content" + ] + }, + { + "type": "paragraph", + "text": "Where search makes the most sense depends on the layout, content, and navigation of your app." + } + ] + }, + { + "heading": "Search in a tab bar", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "You can place search as a visually distinct tab on the trailing side of a tab bar, which keeps search visible and always available as people switch between the sections of your app." + }, + { + "type": "paragraph", + "text": "When someone navigates to the search tab, the search field that appears can start as focused or unfocused." + }, + { + "type": "paragraph", + "text": "Focused" + }, + { + "type": "paragraph", + "text": "Unfocused" + }, + { + "type": "paragraph", + "text": "Start with the search field focused to help people quickly find what they need. When the search field starts focused, the keyboard immediately appears with the search field above it, ready to begin the search. This provides a more transient experience that brings people directly back to their previous tab after they exit search, and is ideal when you want search to resolve quickly and seamlessly." + }, + { + "type": "paragraph", + "text": "Start with the search field unfocused to promote discovery and exploration. When the search field starts unfocused, the search tab expands into an unselected field at the bottom of the screen. This provides space on the rest of the screen for additional discovery or navigation before someone taps the field to begin the search. This is great for an app with a large collection of content to showcase, like Music or TV." + } + ] + }, + { + "heading": "Search in a toolbar", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "As an alternative to search in a tab bar, you can also place search in a toolbar either at the bottom or top of the screen." + }, + { + "type": "list", + "items": [ + "You can include search in a bottom toolbar either as an expanded field or as a toolbar button, depending on how much space is available and how important search is to your app. When someone taps it, it animates into a search field above the keyboard so they can begin typing.", + "You can include search in a top toolbar, also called a navigation bar, where it appears as a toolbar button. When someone taps it, it animates into a search field that appears either above the keyboard or inline at the top if there isn’t space at the bottom." + ] + }, + { + "type": "paragraph", + "text": "Search in a bottom toolbar" + }, + { + "type": "paragraph", + "text": "Search in a top toolbar" + }, + { + "type": "paragraph", + "text": "Place search at the bottom if there’s room. You can either add a search field to an existing toolbar, or as a new toolbar where search is the only item. Search at the bottom is useful in any situation where search is a priority, since it keeps the search experience easy to reach. Examples of apps with search at the bottom in various toolbar layouts include Settings, where it’s the only item, and Mail and Notes, where it fits alongside other important controls." + }, + { + "type": "paragraph", + "text": "Place search at the top when itʼs important to defer to content at the bottom of the screen, or thereʼs no bottom toolbar. Use search at the top in cases where covering the content might interfere with a primary function of the app. The Wallet app, for example, includes event passes in a stack at the bottom of the screen for easy access and viewing at a glance." + } + ] + }, + { + "heading": "Search as an inline field", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "In some cases you might want your app to include a search field inline with content." + }, + { + "type": "paragraph", + "text": "Place search as an inline field when its position alongside the content it searches strengthens that relationship. When you need to filter or search within a single view, it can be helpful to have search appear directly next to content to illustrate that the search applies to it, rather than globally. For example, although the main search in the Music app is in the tab bar, people can navigate to their library and use an inline search field to filter their songs and albums." + }, + { + "type": "paragraph", + "text": "Prefer placing search at the bottom. Generally, even for search that applies to a subset of your app’s content, it’s better to locate search where people can reach it easily. The Settings app, for example, places search at the bottom both for its top-level search and for search in the section for individual apps. If there isn’t space at the bottom (because it’s occupied by a tab bar or other important UI, for example), it’s okay to place search inline at the top." + }, + { + "type": "paragraph", + "text": "When at the top, position an inline search field above the list it searches, and pin it to the top toolbar when scrolling. This helps keep it distinct from search that appears in other locations." + } + ] + }, + { + "heading": "iPadOS, macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The placement and behavior of the search field in iPadOS and macOS is similar; on both platforms, clearing the field exits search and dismisses the keyboard if present. If your app is available on both iPad and Mac, try to keep the search experience as consistent as possible across both platforms." + }, + { + "type": "paragraph", + "text": "iPadOS" + }, + { + "type": "paragraph", + "text": "macOS" + }, + { + "type": "paragraph", + "text": "Put a search field at the trailing side of the toolbar for many common uses. Many apps benefit from the familiar pattern of search in the toolbar, particularly apps with split views or apps that navigate between multiple sources, like Mail, Notes, and Voice Memos. The persistent availability of search at the side of the toolbar gives it a global presence within your app, so it’s generally appropriate to start with a global scope for the initial search." + }, + { + "type": "paragraph", + "text": "Include search at the top of the sidebar when filtering content or navigation there. Apps such as Settings take advantage of search to quickly filter the sidebar and expose sections that may be multiple levels deep, providing a simple way for people to search, preview, and navigate to the section or setting they’re looking for." + }, + { + "type": "paragraph", + "text": "Include search as an item in the sidebar or tab bar when you want an area dedicated to discovery. If your search is paired with rich suggestions, categories, or content that needs more space, it can be helpful to have a dedicated area for it. This is particularly true for apps where browsing and search go hand in hand, like Music and TV, where it provides a unified location to highlight suggested content, categories, and recent searches. A dedicated area also ensures search is always available as people navigate and switch sections of your app." + }, + { + "type": "paragraph", + "text": "In a search field in a dedicated area, consider immediately focusing the field when a person navigates to the section to help people search faster and locate the field itself more easily. An exception to this is on iPad when only a virtual keyboard is available, in which case it’s better to leave the field unfocused to prevent the keyboard from unexpectedly covering the view." + }, + { + "type": "paragraph", + "text": "Account for window resizing with the placement of the search field. On iPad, the search field fluidly resizes with the app window like it does on Mac. However, for compact views on iPad, itʼs important to ensure that search is available where it’s most contextually useful. For example, Notes and Mail place search above the column for the content list when they resize down to a compact view." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A search screen is a specialized keyboard screen that helps people enter search text, displaying search results beneath the keyboard in a fully customizable view. For developer guidance, see UISearchController." + }, + { + "type": "paragraph", + "text": "Provide suggestions to make searching easier. People typically don’t want to do a lot of typing in tvOS. To improve the search experience, provide popular and context-specific search suggestions, including recent searches when available. For developer guidance, see Using suggested searches with a search controller." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When someone taps the search field, the system displays a text-input control that covers the entire screen. The app only returns to the search field after they tap the Cancel or Search button." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Searching" + }, + { + "type": "paragraph", + "text": "Token fields" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adding a search interface to your app — SwiftUI" + }, + { + "type": "paragraph", + "text": "searchable(text:placement:prompt:) — SwiftUI" + }, + { + "type": "paragraph", + "text": "UISearchBar — UIKit" + }, + { + "type": "paragraph", + "text": "UISearchTextField — UIKit" + }, + { + "type": "paragraph", + "text": "NSSearchField — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated guidance for search placement in iOS, consolidated iPadOS and macOS platform considerations, and added guidance for tokens." + ], + [ + "September 12, 2023", + "Combined guidance common to all platforms." + ], + [ + "June 5, 2023", + "Added guidance for using search fields in watchOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "scope control", + "url": "/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens" + }, + { + "title": "Searching", + "url": "/design/human-interface-guidelines/searching" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/search-fields#Best-practices" + }, + { + "title": "segmented control", + "url": "/design/human-interface-guidelines/segmented-controls" + }, + { + "title": "Token fields", + "url": "/design/human-interface-guidelines/token-fields" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/search-fields#Platform-considerations" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/search-fields#iOS" + }, + { + "title": "Search in a tab bar", + "url": "/design/human-interface-guidelines/search-fields#Search-in-a-tab-bar" + }, + { + "title": "Search in a toolbar", + "url": "/design/human-interface-guidelines/search-fields#Search-in-a-toolbar" + }, + { + "title": "Search as an inline field", + "url": "/design/human-interface-guidelines/search-fields#Search-as-an-inline-field" + }, + { + "title": "iPadOS, macOS", + "url": "/design/human-interface-guidelines/search-fields#iPadOS-macOS" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/search-fields#tvOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/search-fields#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/search-fields#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/search-fields#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/search-fields#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/search-fields#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/search-fields#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Segmented controls", + "url": "https://developer.apple.com/design/human-interface-guidelines/segmented-controls", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Within a segmented control, all segments are usually equal in width. Like buttons, segments can contain text or images. Segments can also have text labels beneath them (or beneath the control as a whole)." + }, + { + "type": "paragraph", + "text": "A segmented control offers a single choice from among a set of options, or in macOS, either a single choice or multiple choices. For example, in macOS Keynote people can select only one segment in the alignment options control to align selected text. In contrast, people can choose multiple segments in the font attributes control to combine styles like bold, italics, and underline. The toolbar of a Keynote window also uses a segmented control to let people show and hide various editing panes within the main window area." + }, + { + "type": "paragraph", + "text": "Single choice" + }, + { + "type": "paragraph", + "text": "Multiple choices" + }, + { + "type": "paragraph", + "text": "In addition to representing the state of a single or multiple-choice selection, a segmented control can function as a set of buttons that perform actions without showing a selection state. For example, the Reply, Reply all, and Forward buttons in macOS Mail. For developer guidance, see isMomentary and NSSegmentedControl.SwitchTracking.momentary." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a segmented control to provide closely related choices that affect an object, state, or view. For example, a segmented control in an inspector could let people choose one or more attributes to apply to a selection, or a segmented control in a toolbar could offer a set of actions to perform on the current view." + }, + { + "type": "paragraph", + "text": "In the iOS Health app, a segmented control provides a choice of time ranges for the activity graphs to display." + }, + { + "type": "paragraph", + "text": "Consider a segmented control when it’s important to group functions together, or to clearly show their selection state. Unlike other button styles, segmented controls preserve their grouping regardless of the view size or where they appear. This grouping can also help people understand at a glance which controls are currently selected." + }, + { + "type": "paragraph", + "text": "Keep control types consistent within a single segmented control. Don’t assign actions to segments in a control that otherwise represents selection state, and don’t show a selection state for segments in a control that otherwise performs actions." + }, + { + "type": "paragraph", + "text": "Limit the number of segments in a control. Too many segments can be hard to parse and time-consuming to navigate. Aim for no more than about five to seven segments in a wide interface and no more than about five segments on iPhone." + }, + { + "type": "paragraph", + "text": "In general, keep segment size consistent. When all segments have equal width, a segmented control feels balanced. To the extent possible, it’s best to keep icon and title widths consistent too." + } + ] + }, + { + "heading": "Content", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer using either text or images — not a mix of both — in a single segmented control. Although individual segments can contain text labels or images, mixing the two in a single control can lead to a disconnected and confusing interface." + }, + { + "type": "paragraph", + "text": "As much as possible, use content with a similar size in each segment. Because all segments typically have equal width, it doesn’t look good if content fills some segments but not others." + }, + { + "type": "paragraph", + "text": "Use nouns or noun phrases for segment labels. Write text that describes each segment and uses title-style capitalization. A segmented control that displays text labels doesn’t need introductory text." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider a segmented control to switch between closely related subviews. A segmented control can be useful as a way to quickly switch between related subviews. For example, the segmented control in Calendar’s New Event sheet switches between the subviews for creating a new event and a new reminder. For switching between completely separate sections of an app, use a tab bar instead." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider using introductory text to clarify the purpose of a segmented control. When the control uses symbols or interface icons, you could also add a label below each segment to clarify its meaning. If your app includes tooltips, provide one for each segment in a segmented control." + }, + { + "type": "paragraph", + "text": "Use a tab view in the main window area — instead of a segmented control — for view switching. A tab view supports efficient view switching and is similar in appearance to a box combined with a segmented control. Consider using a segmented control to help people switch views in a toolbar or inspector pane." + }, + { + "type": "paragraph", + "text": "Consider supporting spring loading. On a Mac equipped with a Magic Trackpad, spring loading lets people activate a segment by dragging selected items over it and force clicking without dropping the selected items. People can also continue dragging the items after a segment activates." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider using a split view instead of a segmented control on screens that perform content filtering. People generally find it easy to navigate back and forth between content and filtering options using a split view. Depending on its placement, a segmented control may not be as easy to access." + }, + { + "type": "paragraph", + "text": "Avoid putting other focusable elements close to segmented controls. Segments become selected when focus moves to them, not when people click them. Carefully consider where you position a segmented control relative to other interface elements. If other focusable elements are too close, people might accidentally focus on them when attempting to switch between segments." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When people look at a segmented control that uses icons, the system displays a tooltip that contains the descriptive text you supply." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Split views" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "segmented — SwiftUI" + }, + { + "type": "paragraph", + "text": "UISegmentedControl — UIKit" + }, + { + "type": "paragraph", + "text": "NSSegmentedControl — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/segmented-controls#Best-practices" + }, + { + "title": "Content", + "url": "/design/human-interface-guidelines/segmented-controls#Content" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/segmented-controls#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/segmented-controls#iOS-iPadOS" + }, + { + "title": "tab bar", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/segmented-controls#macOS" + }, + { + "title": "tab view", + "url": "/design/human-interface-guidelines/tab-views" + }, + { + "title": "box", + "url": "/design/human-interface-guidelines/boxes" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/segmented-controls#tvOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/segmented-controls#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/segmented-controls#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/segmented-controls#Related" + }, + { + "title": "Split views", + "url": "/design/human-interface-guidelines/split-views" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/segmented-controls#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/segmented-controls#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Status bars", + "url": "https://developer.apple.com/design/human-interface-guidelines/status-bars", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Obscure content under the status bar. By default, the background of the status bar is transparent, allowing content beneath to show through. This transparency can make it difficult to see information presented in the status bar. If controls are visible behind the status bar, people may attempt to interact with them and be unable to do so. Be sure to keep the status bar readable, and don’t imply that content behind it is interactive. Prefer using a scroll edge effect to place a blurred view behind the status bar. For developer guidance, see ScrollEdgeEffectStyle and UIScrollEdgeEffect." + }, + { + "type": "paragraph", + "text": "Consider temporarily hiding the status bar when displaying full-screen media. A status bar can be distracting when people are paying attention to media. Temporarily hide these elements to provide a more immersive experience. The Photos app, for example, hides the status bar and other interface elements when people browse full-screen photos." + }, + { + "type": "paragraph", + "text": "The Photos app with the status bar visible" + }, + { + "type": "paragraph", + "text": "The Photos app with the status bar hidden" + }, + { + "type": "paragraph", + "text": "Avoid permanently hiding the status bar. Without a status bar, people have to leave your app to check the time or see if they have a Wi-Fi connection. Let people redisplay a hidden status bar with a simple, discoverable gesture. For example, when browsing full-screen photos in the Photos app, a single tap shows the status bar again." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "UIStatusBarStyle — UIKit" + }, + { + "type": "paragraph", + "text": "preferredStatusBarStyle — UIKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/status-bars#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/status-bars#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/status-bars#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/status-bars#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "The menu bar", + "url": "https://developer.apple.com/design/human-interface-guidelines/the-menu-bar", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Mac users are very familiar with the macOS menu bar, and they rely on it to help them learn what an app does and find the commands they need. To help your app or game feel at home in macOS, it’s essential to provide a consistent menu bar experience." + }, + { + "type": "paragraph", + "text": "Menu bar menus on iPad are similar to those on Mac, appearing in the same order and with familiar sets of menu items. When you adopt the menu structure that people expect from their experience on Mac, it helps them immediately understand and take advantage of the menu bar on iPad as well." + }, + { + "type": "paragraph", + "text": "Keyboard shortcuts in iPadOS use the same patterns as in macOS. For guidance, see Standard keyboard shortcuts." + }, + { + "type": "paragraph", + "text": "Menus in the menu bar share most of the appearance and behavior characteristics that all menu types have. To learn about menus in general — and how to organize and label menu items — see Menus." + } + ] + }, + { + "heading": "Anatomy", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When present in the menu bar, the following menus appear in the order listed below." + }, + { + "type": "list", + "items": [ + "YourAppName (you supply a short version of your app’s name for this menu’s title)", + "File", + "Edit", + "Format", + "View", + "App-specific menus, if any", + "Window", + "Help" + ] + }, + { + "type": "paragraph", + "text": "In addition, the macOS menu bar includes the Apple menu on the leading side and menu bar extras on the trailing side. See macOS Platform considerations for guidance." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support the default system-defined menus and their ordering. People expect to find menus and menu items in an order they’re familiar with. In many cases, the system implements the functionality of standard menu items so you don’t have to. For example, when people select text in a standard text field, the system makes the Edit > Copy menu item available." + }, + { + "type": "paragraph", + "text": "Always show the same set of menu items. Keeping menu items visible helps people learn what actions your app supports, even if they’re unavailable in the current context. If a menu bar item isn’t actionable, disable the action instead of hiding it from the menu." + }, + { + "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. For additional guidance, see Menus." + }, + { + "type": "paragraph", + "text": "Support the keyboard shortcuts defined for the standard menu items you include. People expect to use the keyboard shortcuts they already know for standard menu items, like Copy, Cut, Paste, Save, and Print. Define custom keyboard shortcuts only when necessary. For guidance, see Standard keyboard shortcuts." + }, + { + "type": "paragraph", + "text": "Prefer short, one-word menu titles. Various factors — like different display sizes and the presence of menu bar extras — can affect the spacing and appearance of your menus. One-word menu titles work especially well in the menu bar because they take little space and are easy for people to scan. If you need to use more than one word in the menu title, use title-style capitalization." + } + ] + }, + { + "heading": "App menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The app menu lists items that apply to your app or game as a whole, rather than to a specific task, document, or window. To help people quickly identify the active app, the menu bar displays your app name in bold." + }, + { + "type": "paragraph", + "text": "The app menu typically contains the following menu items listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action", + "Guidance" + ], + [ + "About YourAppName", + "Displays the About window for your app, which includes copyright and version information.", + "Prefer a short name of 16 characters or fewer. Don’t include a version number." + ], + [ + "Settings…", + "Opens your settings window, or your app’s page in iPadOS Settings.", + "Use only for app-level settings. If you also offer document-specific settings, put them in the File menu." + ], + [ + "Optional app-specific items", + "Performs custom app-level setting or configuration actions.", + "List custom app-configuration items after the Settings item and within the same group." + ], + [ + "Services (macOS only)", + "Displays a submenu of services from the system and other apps that apply to the current context.", + "" + ], + [ + "Hide YourAppName (macOS only)", + "Hides your app and all of its windows, and then activates the most recently used app.", + "Use the same short app name you supply for the About item." + ], + [ + "Hide Others (macOS only)", + "Hides all other open apps and their windows.", + "" + ], + [ + "Show All (macOS only)", + "Shows all other open apps and their windows behind your app’s windows.", + "" + ], + [ + "Quit YourAppName", + "Quits your app. Pressing Option changes Quit YourAppName to Quit and Keep Windows.", + "Use the same short app name you supply for the About item." + ] + ] + }, + { + "type": "paragraph", + "text": "Display the About menu item first. Include a separator after the About menu item so that it appears by itself in a group." + } + ] + }, + { + "heading": "File menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The File menu contains commands that help people manage the files or documents an app supports. If your app doesn’t handle any types of files, you can rename or eliminate this menu." + }, + { + "type": "paragraph", + "text": "The File menu typically contains the following menu items listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action", + "Guidance" + ], + [ + "New Item", + "Creates a new document, file, or window.", + "For Item, use a term that names the type of item your app creates. For example, Calendar uses Event and Calendar." + ], + [ + "Open", + "Can open the selected item or present an interface in which people select an item to open.", + "If people need to select an item in a separate interface, an ellipsis follows the command to indicate that more input is required." + ], + [ + "Open Recent", + "Displays a submenu that lists recently opened documents and files that people can select, and typically includes a Clear Menu item.", + "List document and filenames that people recognize in the submenu; don’t display file paths. List the documents in the order people last opened them, with the most recently opened document first." + ], + [ + "Close", + "Closes the current window or document. Pressing Option changes Close to Close All. For a tab-based window, Close Tab replaces Close.", + "In a tab-based window, consider adding a Close Window item to let people close the entire window with one click or tap." + ], + [ + "Close Tab", + "Closes the current tab in a tab-based window. Pressing Option changes Close Tab to Close Other Tabs.", + "" + ], + [ + "Close File", + "Closes the current file and all its associated windows.", + "Consider supporting this menu item if your app can open multiple views of the same file." + ], + [ + "Save", + "Saves the current document or file.", + "Automatically save changes periodically as people work so they don’t need to keep choosing File > Save. For a new document, prompt people for a name and location. If you need to let people save a file in multiple formats, prefer a pop-up menu that lets people choose a format in the Save sheet." + ], + [ + "Save All", + "Saves all open documents.", + "" + ], + [ + "Duplicate", + "Duplicates the current document, leaving both documents open. Pressing Option changes Duplicate to Save As.", + "Prefer Duplicate to menu items like Save As, Export, Copy To, and Save To because these items don’t clarify the relationship between the original file and the new one." + ], + [ + "Rename…", + "Lets people change the name of the current document.", + "" + ], + [ + "Move To…", + "Prompts people to choose a new location for the document.", + "" + ], + [ + "Export As…", + "Prompts people for a name, output location, and export file format. After exporting the file, the current document remains open; the exported file doesn’t open.", + "Reserve the Export As item for when you need to let people export content in a format your app doesn’t typically handle." + ], + [ + "Revert To", + "When people turn on autosaving, displays a submenu that lists recent document versions and an option to display the version browser. After people choose a version to restore, it replaces the current document.", + "" + ], + [ + "Page Setup…", + "Opens a panel for specifying printing parameters like paper size and printing orientation. A document can save the printing parameters that people specify.", + "Include the Page Setup item if you need to support printing parameters that apply to a specific document. Parameters that are global in nature, like a printer’s name, or that people change frequently, like the number of copies to print, belong in the Print panel." + ], + [ + "Print…", + "Opens the standard Print panel, which lets people print to a printer, send a fax, or save as a PDF.", + "" + ] + ] + } + ] + }, + { + "heading": "Edit menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Edit menu lets people make changes to content in the current document or text container, and provides commands for interacting with the Clipboard. Because many editing commands apply to any editable content, the Edit menu is useful even in apps that aren’t document-based." + }, + { + "type": "paragraph", + "text": "Determine whether Find menu items belong in the Edit menu. For example, if your app lets people search for files or other types of objects, Find menu items might be more appropriate in the File menu." + }, + { + "type": "paragraph", + "text": "The Edit menu typically contains the following top-level menu items, listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action", + "Guidance" + ], + [ + "Undo", + "Reverses the effect of the previous user operation.", + "Clarify the target of the undo. For example, if people just selected a menu item, you can append the item’s title, such as Undo Paste and Match Style. For a text entry operation, you might append the word Typing to give Undo Typing." + ], + [ + "Redo", + "Reverses the effect of the previous Undo operation.", + "Clarify the target of the redo. For example, if people just reversed a menu item selection, you can append the item’s title, such as Redo Paste and Match Style. For a text entry operation, you might append the word Typing to give Redo Typing." + ], + [ + "Cut", + "Removes the selected data and stores it on the Clipboard, replacing the previous contents of the Clipboard.", + "" + ], + [ + "Copy", + "Duplicates the selected data and stores it on the Clipboard.", + "" + ], + [ + "Paste", + "Inserts the contents of the Clipboard at the current insertion point. The Clipboard contents remain unchanged, permitting people to choose Paste multiple times.", + "" + ], + [ + "Paste and Match Style", + "Inserts the contents of the Clipboard at the current insertion point, matching the style of the inserted text to the surrounding text.", + "" + ], + [ + "Delete", + "Removes the selected data, but doesn’t place it on the Clipboard.", + "Provide a Delete menu item instead of an Erase or Clear menu item. Choosing Delete is the equivalent of pressing the Delete key, so it’s important for the naming to be consistent." + ], + [ + "Select All", + "Highlights all selectable content in the current document or text container.", + "" + ], + [ + "Find", + "Displays a submenu containing menu items for performing search operations in the current document or text container. Standard submenus include: Find, Find and Replace, Find Next, Find Previous, Use Selection for Find, and Jump to Selection.", + "" + ], + [ + "Spelling and Grammar", + "Displays a submenu containing menu items for checking for and correcting spelling and grammar in the current document or text container. Standard submenus include: Show Spelling and Grammar, Check Document Now, Check Spelling While Typing, Check Grammar With Spelling, and Correct Spelling Automatically.", + "" + ], + [ + "Substitutions", + "Displays a submenu containing items that let people toggle automatic substitutions while they type in a document or text container. Standard submenus include: Show Substitutions, Smart Copy/Paste, Smart Quotes, Smart Dashes, Smart Links, Data Detectors, and Text Replacement.", + "" + ], + [ + "Transformations", + "Displays a submenu containing items that transform selected text. Standard submenus include: Make Uppercase, Make Lowercase, and Capitalize.", + "" + ], + [ + "Speech", + "Displays a submenu containing Start Speaking and Stop Speaking items, which control when the system audibly reads selected text.", + "" + ], + [ + "Start Dictation", + "Opens the dictation window and converts spoken words into text that’s added at the current insertion point. The system automatically adds the Start Dictation menu item at the bottom of the Edit menu.", + "" + ], + [ + "Emoji & Symbols", + "Displays a Character Viewer, which includes emoji, symbols, and other characters people can insert at the current insertion point. The system automatically adds the Emoji & Symbols menu item at the bottom of the Edit menu.", + "" + ] + ] + } + ] + }, + { + "heading": "Format menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Format menu lets people adjust text formatting attributes in the current document or text container. You can exclude this menu if your app doesn’t support formatted text editing." + }, + { + "type": "paragraph", + "text": "The Format menu typically contains the following top-level menu items, listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action" + ], + [ + "Font", + "Displays a submenu containing items for adjusting font attributes of the selected text. Standard submenus include: Show Fonts, Bold, Italic, Underline, Bigger, Smaller, Show Colors, Copy Style, and Paste Style." + ], + [ + "Text", + "Displays a submenu containing items for adjusting text attributes of the selected text. Standard submenus include: Align Left, Align Center, Justify, Align Right, Writing Direction, Show Ruler, Copy Ruler, and Paste Ruler." + ] + ] + } + ] + }, + { + "heading": "View menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The View menu lets people customize the appearance of all an app’s windows, regardless of type." + }, + { + "type": "important", + "text": "ImportantThe View menu doesn’t include items for navigating between or managing specific windows; the Window menu provides these commands." + }, + { + "type": "paragraph", + "text": "Provide a View menu even if your app supports only a subset of the standard view functions. For example, if your app doesn’t include a tab bar, toolbar, or sidebar, but does support full-screen mode, provide a View menu that includes only the Enter/Exit Full Screen menu item." + }, + { + "type": "paragraph", + "text": "Ensure that each show/hide item title reflects the current state of the corresponding view. For example, when the toolbar is hidden, provide a Show Toolbar menu item; when the toolbar is visible, provide a Hide Toolbar menu item." + }, + { + "type": "paragraph", + "text": "The View menu typically contains the following top-level menu items, listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action" + ], + [ + "Show/Hide Tab Bar", + "Toggles the visibility of the tab bar above the body area in a tab-based window" + ], + [ + "Show All Tabs/Exit Tab Overview", + "Enters and exits a view (similar to Mission Control) that provides an overview of all open tabs in a tab-based window" + ], + [ + "Show/Hide Toolbar", + "In a window that includes a toolbar, toggles the toolbar’s visibility" + ], + [ + "Customize Toolbar", + "In a window that includes a toolbar, opens a view that lets people customize toolbar items" + ], + [ + "Show/Hide Sidebar", + "In a window that includes a sidebar, toggles the sidebar’s visibility" + ], + [ + "Enter/Exit Full Screen", + "In an app that supports a full-screen experience, opens the window at full-screen size in a new space" + ] + ] + } + ] + }, + { + "heading": "App-specific menus", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Your app’s custom menus appear in the menu bar between the View menu and the Window menu. For example, Safari’s menu bar includes app-specific History and Bookmarks menus." + }, + { + "type": "paragraph", + "text": "Provide app-specific menus for custom commands. People look in the menu bar when searching for app-specific commands, especially when using an app for the first time. Even when commands are available elsewhere in your app, it’s important to list them in the menu bar. Putting commands in the menu bar makes them easier for people to find, lets you assign keyboard shortcuts to them, and makes them more accessible to people using Full Keyboard Access. Excluding commands from the menu bar — even infrequently used or advanced commands — risks making them difficult for everyone to find." + }, + { + "type": "paragraph", + "text": "As much as possible, reflect your app’s hierarchy in app-specific menus. For example, Mail lists the Mailbox, Message, and Format menus in an order that mirrors the relationships of these items: mailboxes contain messages, and messages contain formatting." + }, + { + "type": "paragraph", + "text": "Aim to list app-specific menus in order from most to least general or commonly used. People tend to expect menus in the leading end of a list to be more specialized than menus in the trailing end." + } + ] + }, + { + "heading": "Window menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Window menu lets people navigate, organize, and manage an app’s windows." + }, + { + "type": "important", + "text": "ImportantThe Window menu doesn’t help people customize the appearance of windows or close them. To customize a window, people use commands in the View menu; to close a window, people choose Close in the File menu." + }, + { + "type": "paragraph", + "text": "Provide a Window menu even if your app has only one window. Include the Minimize and Zoom menu items so people using Full Keyboard Access can use the keyboard to invoke these functions." + }, + { + "type": "paragraph", + "text": "Consider including menu items for showing and hiding panels. A panel provides information, configuration options, or tools for interacting with content in a primary window, and typically appears only when people need it. There’s no need to provide access to the font panel or text color panel because the Format menu lists these panels." + }, + { + "type": "paragraph", + "text": "The Window menu typically contains the following top-level menu items, listed in the following order." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action", + "Guidance" + ], + [ + "Minimize", + "Minimizes the active window to the Dock. Pressing the Option key changes this item to Minimize All.", + "" + ], + [ + "Zoom", + "Toggles between a predefined size appropriate to the window’s content and the window size people set. Pressing the Option key changes this item to Zoom All.", + "Avoid using Zoom to enter or exit full-screen mode. The View menu supports these functions." + ], + [ + "Show Previous Tab", + "Shows the tab before the current tab in a tab-based window.", + "" + ], + [ + "Show Next Tab", + "Shows the tab after the current tab in a tab-based window.", + "" + ], + [ + "Move Tab to New Window", + "Opens the current tab in a new window.", + "" + ], + [ + "Merge All Windows", + "Combines all open windows into a single tabbed window.", + "" + ], + [ + "Enter/Exit Full Screen", + "In an app that supports a full-screen experience, opens the window at full-screen size in a new space.", + "Include this item in the Window menu only if your app doesn’t have a View menu. In this scenario, continue to provide separate Minimize and Zoom menu items." + ], + [ + "Bring All to Front", + "Brings all an app’s open windows to the front, maintaining their onscreen location, size, and layering order. (Clicking the app icon in the Dock has the same effect.) Pressing the Option key changes this item to Arrange in Front, which brings an app’s windows to the front in a neatly tiled arrangement.", + "" + ], + [ + "Name of an open app-specific window", + "Brings the selected window to the front.", + "List the currently open windows in alphabetical order for easy scanning. Avoid listing panels or other modal views." + ] + ] + } + ] + }, + { + "heading": "Help menu", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Help menu — located at the trailing end of the menu bar — provides access to an app’s help documentation. When you use the Help Book format for this documentation, macOS automatically includes a search field at the top of the Help menu." + }, + { + "type": "table", + "rows": [ + [ + "Menu item", + "Action", + "Guidance" + ], + [ + "Send YourAppName Feedback to Apple", + "Opens the Feedback Assistant, in which people can provide feedback.", + "" + ], + [ + "YourAppName Help", + "When the content uses the Help Book format, opens the content in the built-in Help Viewer.", + "" + ], + [ + "Additional Item", + "", + "Use a separator between your primary help documentation and additional items, which might include registration information or release notes. Keep the total the number of items you list in the Help menu small to avoid overwhelming people with too many choices when they need help. Alternatively, consider linking to additional items from within your help documentation." + ] + ] + }, + { + "type": "paragraph", + "text": "For guidance, see Offering help; for developer guidance, see NSHelpManager." + } + ] + }, + { + "heading": "Dynamic menu items", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In rare cases, it can make sense to present a dynamic menu item, which is a menu item that changes its behavior when people choose it while pressing a modifier key (Control, Option, Shift, or Command). For example, the Minimize item in the Window menu changes to Minimize All when people press the Option key." + }, + { + "type": "paragraph", + "text": "Avoid making a dynamic menu item the only way to accomplish a task. Dynamic menu items are hidden by default, so they’re best suited to offer shortcuts to advanced actions that people can accomplish in other ways. For example, if someone hasn’t discovered the Minimize All dynamic menu item in the Window menu, they can still minimize each open window." + }, + { + "type": "paragraph", + "text": "Use dynamic menu items primarily in menu bar menus. Adding a dynamic menu item to contextual or Dock menus can make the item even harder for people to discover." + }, + { + "type": "paragraph", + "text": "Require only a single modifier key to reveal a dynamic menu item. It can be physically awkward to press more than one key while simultaneously opening a menu and choosing a menu item, in addition to reducing the discoverability of the dynamic behavior. For developer guidance, see isAlternate." + }, + { + "type": "tip", + "text": "TipmacOS automatically sets the width of a menu to hold the widest item, including dynamic menu items." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The menu bar displays the top-level menus for your app or game, including both system-provided menus and any custom ones you choose to add. People reveal the menu bar by moving the pointer to the top edge of the screen, or swiping down from it. When visible, the menu bar occupies the same vertical space as the status bar at the top edge of the screen." + }, + { + "type": "paragraph", + "text": "As with the macOS menu bar, the iPadOS menu bar provides a familiar way for people to learn what an app does, find the commands they need, and discover keyboard shortcuts. While they are similar in most respects, there are a few key differences between the menu bars on each platform." + }, + { + "type": "table", + "rows": [ + [ + "", + "iPadOS", + "macOS" + ], + [ + "Menu bar visibility", + "Hidden until revealed", + "Visible by default" + ], + [ + "Horizontal alignment", + "Centered", + "Leading side" + ], + [ + "Menu bar extras", + "Not available", + "System default and custom" + ], + [ + "Window controls", + "In the menu bar when the app is full screen", + "Never in the menu bar" + ], + [ + "Apple menu", + "Not available", + "Always available" + ], + [ + "App menu", + "About, Services, and app visibility-related items not available", + "Always available" + ] + ] + }, + { + "type": "paragraph", + "text": "Because the menu bar is often hidden when running an app full screen, ensure that people can access all of your app’s functions through its UI. In particular, always offer other ways to accomplish tasks assigned to dynamic menu items, since these are only available when a hardware keyboard is connected. Avoid using the menu bar as a catch-all location for functionality that doesn’t fit in elsewhere." + }, + { + "type": "paragraph", + "text": "Reserve the YourAppName > Settings menu item for opening your app’s page in iPadOS Settings. If your app includes its own internal preferences area, link to it with a separate menu item beneath Settings in the same group. Place any other custom app-wide configuration options in this section as well." + }, + { + "type": "paragraph", + "text": "For apps with tab-style navigation, consider adding each tab as a menu item in the View menu. Since each tab is a different view of the app, the View menu is a natural place to offer an additional way to navigate between tabs. If you do this, consider assigning key bindings to each tab to make navigation even more convenient." + }, + { + "type": "paragraph", + "text": "Consider grouping menu items into submenus to conserve vertical space. Menu item rows on iPad use more space than on Mac to make them easier to tap. Because of this, and the smaller screen sizes of some iPads, it can be helpful to group related items into submenus more frequently than in the menu bar on Mac." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The menu bar in macOS includes the Apple menu, which is always the first item on the leading side of the menu bar. The Apple menu includes system-defined menu items that are always available, and you can’t modify or remove it. Space permitting, the system can also display menu bar extras in the trailing end of the menu bar. For guidance, see Menu bar extras." + }, + { + "type": "paragraph", + "text": "When menu bar space is constrained, the system prioritizes the display of menus and essential menu bar extras. To ensure that menus remain readable, the system may decrease the space between the titles, truncating them if necessary." + }, + { + "type": "paragraph", + "text": "When people enter full-screen mode, the menu bar typically hides until they reveal it by moving the pointer to the top of the screen. For guidance, see Going full screen." + } + ] + }, + { + "heading": "Menu bar extras", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "A menu bar extra exposes app-specific functionality using an icon that appears in the menu bar when your app is running, even when it’s not the frontmost app. Menu bar extras are on the opposite side of the menu bar from your app’s menus. For developer guidance, see MenuBarExtra." + }, + { + "type": "paragraph", + "text": "When necessary, the system hides menu bar extras to make room for app menus. Similarly, if there are too many menu bar extras, the system may hide some to avoid crowding app menus." + }, + { + "type": "paragraph", + "text": "Consider using a symbol to represent your menu bar extra. You can create an icon or you can choose one of the SF Symbols, using it as-is or customizing it 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 so it looks good on both dark and light menu bars, and when your menu bar extra is selected. The menu bar’s height is 24 pt." + }, + { + "type": "paragraph", + "text": "Display a menu — not a popover — when people click your menu bar extra. Unless the app functionality you want to expose is too complex for a menu, avoid presenting it in a popover." + }, + { + "type": "paragraph", + "text": "Let people — not your app — decide whether to put your menu bar extra in the menu bar. Typically, people add a menu bar extra to the menu bar by changing a setting in an app’s settings window. To ensure discoverability, however, consider giving people the option of doing so during setup." + }, + { + "type": "paragraph", + "text": "Avoid relying on the presence of menu bar extras. The system hides and shows menu bar extras regularly, and you can’t be sure which other menu bar extras people have chosen to display or predict the location of your menu bar extra." + }, + { + "type": "paragraph", + "text": "Consider exposing app-specific functionality in other ways, too. For example, you can provide a Dock menu that appears when people Control-click your app’s Dock icon. People can hide or choose not to use your menu bar extra, but a Dock menu is aways available when your app is running." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Menus" + }, + { + "type": "paragraph", + "text": "Dock menus" + }, + { + "type": "paragraph", + "text": "Standard keyboard shortcuts" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "CommandMenu — SwiftUI" + }, + { + "type": "paragraph", + "text": "Adding menus and shortcuts to the menu bar and user interface — UIKit" + }, + { + "type": "paragraph", + "text": "NSStatusBar — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Added guidance for the menu bar in iPadOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Standard keyboard shortcuts", + "url": "/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "Anatomy", + "url": "/design/human-interface-guidelines/the-menu-bar#Anatomy" + }, + { + "title": "macOS Platform considerations", + "url": "/design/human-interface-guidelines/the-menu-bar#macOS" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/the-menu-bar#Best-practices" + }, + { + "title": "Standard icons", + "url": "/design/human-interface-guidelines/icons#Standard-icons" + }, + { + "title": "App menu", + "url": "/design/human-interface-guidelines/the-menu-bar#App-menu" + }, + { + "title": "settings", + "url": "/design/human-interface-guidelines/settings" + }, + { + "title": "File menu", + "url": "/design/human-interface-guidelines/the-menu-bar#File-menu" + }, + { + "title": "Edit menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Edit-menu" + }, + { + "title": "Format menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Format-menu" + }, + { + "title": "View menu", + "url": "/design/human-interface-guidelines/the-menu-bar#View-menu" + }, + { + "title": "Window menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Window-menu" + }, + { + "title": "tab bar", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "toolbar", + "url": "/design/human-interface-guidelines/toolbars" + }, + { + "title": "sidebar", + "url": "/design/human-interface-guidelines/sidebars" + }, + { + "title": "full-screen experience", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "App-specific menus", + "url": "/design/human-interface-guidelines/the-menu-bar#App-specific-menus" + }, + { + "title": "panel", + "url": "/design/human-interface-guidelines/panels" + }, + { + "title": "Help menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Help-menu" + }, + { + "title": "Offering help", + "url": "/design/human-interface-guidelines/offering-help" + }, + { + "title": "Dynamic menu items", + "url": "/design/human-interface-guidelines/the-menu-bar#Dynamic-menu-items" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/the-menu-bar#Platform-considerations" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/the-menu-bar#iPadOS" + }, + { + "title": "status bar", + "url": "/design/human-interface-guidelines/status-bars" + }, + { + "title": "Menu bar extras", + "url": "/design/human-interface-guidelines/the-menu-bar#Menu-bar-extras" + }, + { + "title": "icon", + "url": "/design/human-interface-guidelines/icons" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "popover", + "url": "/design/human-interface-guidelines/popovers" + }, + { + "title": "Dock menu", + "url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/the-menu-bar#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/the-menu-bar#Related" + }, + { + "title": "Dock menus", + "url": "/design/human-interface-guidelines/dock-menus" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/the-menu-bar#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/the-menu-bar#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/the-menu-bar#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Token fields", + "url": "https://developer.apple.com/design/human-interface-guidelines/token-fields", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "For example, Mail uses token fields for the address fields in the compose window. As people enter recipients, Mail converts the text that represents each recipient’s name into a token. People can select these recipient tokens and drag to reorder them or move them into a different field." + }, + { + "type": "paragraph", + "text": "You can configure a token field to present people with a list of suggestions as they enter text into the field. For example, Mail suggests recipients as people type in an address field. When people select a suggested recipient, Mail inserts the recipient into the field as a token." + }, + { + "type": "paragraph", + "text": "An individual token can also include a contextual menu that offers information about the token or editing options. For example, a recipient token in Mail includes a contextual menu with commands for editing the recipient name, marking the recipient as a VIP, and viewing the recipient’s contact card, among others." + }, + { + "type": "paragraph", + "text": "Tokens can also represent search terms in some situations; for guidance, see Search fields." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Add value with a context menu. People often benefit from a context menu with additional options or information about a token." + }, + { + "type": "paragraph", + "text": "Consider providing additional ways to convert text into tokens. By default, text people enter turns into a token whenever they type a comma. You can specify additional shortcuts, such as pressing Return, that also invoke this action." + }, + { + "type": "paragraph", + "text": "Consider customizing the delay the system uses before showing suggested tokens. By default, suggestions appear immediately. However, suggestions that appear too quickly may distract people while they’re typing. If your app suggests tokens, consider adjusting the delay to a comfortable level." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, tvOS, visionOS, and watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Text fields" + }, + { + "type": "paragraph", + "text": "Search fields" + }, + { + "type": "paragraph", + "text": "Context menus" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "NSTokenField — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Search fields", + "url": "/design/human-interface-guidelines/search-fields" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/token-fields#Best-practices" + }, + { + "title": "context menu", + "url": "https://developer.apple.com/design/human-interface-guidelines/context-menus" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/token-fields#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/token-fields#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/token-fields#Related" + }, + { + "title": "Text fields", + "url": "/design/human-interface-guidelines/text-fields" + }, + { + "title": "Context menus", + "url": "/design/human-interface-guidelines/context-menus" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/token-fields#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Toolbars", + "url": "https://developer.apple.com/design/human-interface-guidelines/toolbars", + "category": "general", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A toolbar consists of one or more sets of controls arranged horizontally along the top or bottom edge of the view, grouped into logical sections." + }, + { + "type": "paragraph", + "text": "Toolbars act on content in the view, facilitate navigation, and help orient people in the app. They include three types of content:" + }, + { + "type": "list", + "items": [ + "The title of the current view", + "Navigation controls, like back and forward, and search fields", + "Actions, or bar items, like buttons and menus" + ] + }, + { + "type": "paragraph", + "text": "In contrast to a toolbar, a tab bar is specifically for navigating between areas of an app." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Choose items deliberately to avoid overcrowding. People need to be able to distinguish and activate each item, so you don’t want to put too many items in the toolbar. To accommodate variable view widths, define which items move to the overflow menu as the toolbar becomes narrower." + }, + { + "type": "note", + "text": "NoteThe system automatically adds an overflow menu in macOS or iPadOS when items no longer fit. Don’t add an overflow menu manually, and avoid layouts that cause toolbar items to overflow by default." + }, + { + "type": "paragraph", + "text": "Add a More menu to contain additional actions. Prioritize less important actions for inclusion in the More menu. Try to include all actions in the toolbar if possible, and only add this menu if you really need it." + }, + { + "type": "paragraph", + "text": "The standard toolbar in macOS Notes includes a More menu with extra commands." + }, + { + "type": "paragraph", + "text": "As the window narrows, the More menu moves into an overflow menu along with other toolbar items that no longer fit." + }, + { + "type": "paragraph", + "text": "In iPadOS and macOS apps, consider letting people customize the toolbar to include their most common items. Toolbar customization is especially useful in apps that provide a lot of items — or that include advanced functionality that not everyone needs — and in apps that people tend to use for long periods of time. For example, it works well to make a range of editing actions available for toolbar customization, because people often use different types of editing commands based on their work style and their current project." + }, + { + "type": "paragraph", + "text": "Reduce the use of toolbar backgrounds and tinted controls. Any custom backgrounds and appearances you use might overlay or interfere with background effects that the system provides. Instead, use the content layer to inform the color and appearance of the toolbar, and use a ScrollEdgeEffectStyle when necessary to distinguish the toolbar area from the content area. This approach helps your app express its unique personality without distracting from content." + }, + { + "type": "paragraph", + "text": "Avoid applying a similar color to toolbar item labels and content layer backgrounds. If your app already has bright, colorful content in the content layer, prefer using the default monochromatic appearance of toolbars. For more guidance, see Liquid Glass color." + }, + { + "type": "paragraph", + "text": "Prefer using standard components in a toolbar. By default, standard buttons, text fields, headers, and footers have corner radii that are concentric with bar corners. If you need to create a custom component, ensure that its corner radius is also concentric with the bar’s corners." + }, + { + "type": "paragraph", + "text": "Consider temporarily hiding toolbars for a distraction-free experience. Sometimes people appreciate a minimal interface to reduce distractions or reveal more content. If you support this, do so contextually when it makes the most sense, and offer ways to reliably restore hidden interface elements. For guidance, see Going full screen. For guidance specific to visionOS, see Immersive experiences." + } + ] + }, + { + "heading": "Titles", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Provide a useful title for each window. A title helps people confirm their location as they navigate your app, and differentiates between the content of multiple open windows. If titling a toolbar seems redundant, you can leave the title area empty. For example, Notes doesn’t title the current note when a single window is open, because the first line of content typically supplies sufficient context. However, when opening notes in separate windows, the system titles them with the first line of content so people can tell them apart." + }, + { + "type": "paragraph", + "text": "Don’t title windows with your app name. Your app’s name doesn’t provide useful information about your content hierarchy or any window or area in your app, so it doesn’t work well as a title." + }, + { + "type": "paragraph", + "text": "Write a concise title. Aim for a word or short phrase that distills the purpose of the window or view, and keep the title under 15 characters long so you leave enough room for other controls." + } + ] + }, + { + "heading": "Navigation", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A toolbar with navigation controls appears at the top of a window, helping people move through a hierarchy of content. A toolbar also often contains a search field for quick navigation between areas or pieces of content. In iOS, a navigation-specific toolbar is sometimes called a navigation bar." + }, + { + "type": "paragraph", + "text": "Use the standard Back and Close buttons. People know that the standard Back button lets them retrace their steps through a hierarchy of information, and the standard Close button closes a modal view. Prefer the standard symbols for each, and don’t use a text label that says Back or Close. If you create a custom version of either, make sure it still looks the same, behaves as people expect, and matches the rest of your interface, and ensure you consistently implement it throughout your app or game. For guidance, see Icons." + } + ] + }, + { + "heading": "Actions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Provide actions that support the main tasks people perform. In general, prioritize the commands that people are most likely to want. These commands are often the ones people use most frequently, but in some apps it might make sense to prioritize commands that map to the highest level or most important objects people work with." + }, + { + "type": "paragraph", + "text": "Make sure the meaning of each control is clear. Don’t make people guess or experiment to figure out what a toolbar item does. Prefer simple, recognizable symbols for items instead of text, except for actions like edit that aren’t well-represented by symbols. For guidance on symbols that represent common actions, see Standard icons." + }, + { + "type": "paragraph", + "text": "Prefer system-provided symbols without borders. System-provided symbols are familiar, automatically receive appropriate coloring and vibrancy, and respond consistently to user interactions. Borders (like outlined circle symbols) aren’t necessary because the section provides a visible container, and the system defines hover and selection state appearances automatically. For guidance, see SF Symbols." + }, + { + "type": "paragraph", + "text": "Use the .prominent style for key actions such as Done or Submit. This separates and tints the action so there’s a clear focal point. Only specify one primary action, and put it on the trailing side of the toolbar." + } + ] + }, + { + "heading": "Item groupings", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can position toolbar items in three locations: the leading edge, center area, and trailing edge of the toolbar. These areas provide familiar homes for navigation controls, window or document titles, common actions, and search." + }, + { + "type": "list", + "items": [ + "Leading edge. Elements that let people return to the previous document and show or hide a sidebar appear at the far leading edge, followed by the view title. Next to the title, the toolbar can include a document menu that contains standard and app-specific commands that affect the document as a whole, such as Duplicate, Rename, Move, and Export. To ensure that these items are always available, items on the toolbar’s leading edge aren’t customizable.", + "Center area. Common, useful controls appear in the center area, and the view title can appear here if it’s not on the leading edge. In macOS and iPadOS, people can add, remove, and rearrange items here if you let them customize the toolbar, and items in this section automatically collapse into the system-managed overflow menu when the window shrinks enough in size.", + "Trailing edge. The trailing edge contains important items that need to remain available, buttons that open nearby inspectors, an optional search field, and the More menu that contains additional items and supports toolbar customization. It also includes a primary action like Done when one exists. Items on the trailing edge remain visible at all window sizes." + ] + }, + { + "type": "paragraph", + "text": "To position items in the groupings you want, pin them to the leading edge, center, or trailing edge, and insert space between buttons or other items where appropriate." + }, + { + "type": "paragraph", + "text": "Group toolbar items logically by function and frequency of use. For example, Keynote includes several sections that are based on functionality, including one for presentation-level commands, one for playback commands, and one for object insertion." + }, + { + "type": "paragraph", + "text": "Group navigation controls and critical actions like Done, Close, or Save in dedicated, familiar, and visually distinct sections. This reflects their importance and helps people discover and understand these actions." + }, + { + "type": "paragraph", + "text": "Keep consistent groupings and placement across platforms. This helps people develop familiarity with your app and trust that it behaves similarly regardless of where they use it." + }, + { + "type": "paragraph", + "text": "Minimize the number of groups. Too many groups of controls can make a toolbar feel cluttered and confusing, even with the added space on iPad and Mac. In general, aim for a maximum of three." + }, + { + "type": "paragraph", + "text": "Keep actions with text labels separate. Placing an action with a text label next to an action with a symbol can create the illusion of a single action with a combined text and symbol, leading to confusion and misinterpretation. If your toolbar includes multiple text-labeled buttons, the text of those buttons may appear to run together, making the buttons indistinguishable. Add separation by inserting fixed space between the buttons. For developer guidance, see UIBarButtonItem.SystemItem.fixedSpace." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for tvOS." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Prioritize only the most important items for inclusion in the main toolbar area. Because space is so limited, carefully consider which actions are essential to your app and include those first. Create a More menu to include additional items." + }, + { + "type": "paragraph", + "text": "Use a large title to help people stay oriented as they navigate and scroll. By default, a large title transitions to a standard title as people begin scrolling the content, and transitions back to large when people scroll to the top, reminding them of their current location. For developer guidance, see prefersLargeTitles." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider combining a toolbar with a tab bar. In iPadOS, a toolbar and a tab bar can coexist in the same horizontal space at the top of the view. This is particularly useful for layouts where you want to navigate between a few main app areas while keeping the full width of the window available for content. For guidance, see Layout and Windows." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In a macOS app, the toolbar resides in the frame at the top of a window, either below or integrated with the title bar. Note that window titles can display inline with controls, and toolbar items don’t include a bezel." + }, + { + "type": "paragraph", + "text": "Make every toolbar item available as a command in the menu bar. Because people can customize the toolbar or hide it, it can’t be the only place that presents a command. In contrast, it doesn’t make sense to provide a toolbar item for every menu item, because not all menu commands are important enough or used often enough to warrant space in the toolbar." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In visionOS, the system-provided toolbar appears along the bottom edge of a window, above the window-management controls, and in a parallel plane that’s slightly in front of the window along the z-axis." + }, + { + "type": "paragraph", + "text": "To maintain the legibility of toolbar items as content scrolls behind them, visionOS uses a variable blur in the bar background. The variable blur anchors the bar above the scrolling content while letting the view’s glass material remain uniform and undivided." + }, + { + "type": "paragraph", + "text": "In visionOS, you can supply either a symbol or a text label for each toolbar item. When people look at a toolbar item that contains a symbol, visionOS reveals the text label, providing additional information." + }, + { + "type": "paragraph", + "text": "Prefer using a system-provided toolbar. The standard toolbar has a consistent and familiar appearance and is optimized to work well with eye and hand input. In addition, the system automatically places a standard toolbar in the correct position in relation to its window." + }, + { + "type": "paragraph", + "text": "Avoid creating a vertical toolbar. In visionOS, tab bars are vertical, so presenting a vertical toolbar could confuse people." + }, + { + "type": "paragraph", + "text": "Try to prevent windows from resizing below the width of the toolbar. visionOS doesn’t include a menu bar where each app lists all its actions, so it’s important for the toolbar to provide reliable access to essential controls regardless of a window’s size." + }, + { + "type": "paragraph", + "text": "If your app can enter a modal state, consider offering contextually relevant toolbar controls. For example, a photo-editing app might enter a modal state to help people perform a multistep editing task. In this scenario, the controls in the modal editing view are different from the controls in the main window. Be sure to reinstate the window’s standard toolbar controls when the app exits the modal state." + }, + { + "type": "paragraph", + "text": "Avoid using a pull-down menu in a toolbar. A pull-down menu lets you offer additional actions related to a toolbar item, but can be difficult for people to discover and may clutter your interface. Because a toolbar is located at the bottom edge of a window in visionOS, a pull-down menu might obscure the standard window controls that appear below the bottom edge. For guidance, see Pull-down buttons." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A toolbar button lets you offer important app functionality in a view that displays related content. You can place toolbar buttons in the top corners or along the bottom. If you place these buttons above scrolling content, the buttons always remain visible, as the content scrolls under them." + }, + { + "type": "paragraph", + "text": "Top toolbar buttons" + }, + { + "type": "paragraph", + "text": "Bottom toolbar buttons" + }, + { + "type": "paragraph", + "text": "For developer guidance, see topBarLeading, topBarTrailing, or bottomBar." + }, + { + "type": "paragraph", + "text": "You can also place a button in the scrolling view. By default, a scrolling toolbar button remains hidden until people reveal it by scrolling up. People frequently scroll to the top of a scrolling view, so discovering a toolbar button is automatic." + }, + { + "type": "paragraph", + "text": "Toolbar button hidden" + }, + { + "type": "paragraph", + "text": "Toolbar button shown" + }, + { + "type": "paragraph", + "text": "For developer guidance, see primaryAction." + }, + { + "type": "paragraph", + "text": "Use a scrolling toolbar button for an important action that isn’t a primary app function. A toolbar button gives you the flexibility to offer important functionality in a view whose primary purpose is related to that functionality, but may not be the same. For example, Mail provides the essential New Message action in a toolbar button at the top of the Inbox view. The primary purpose of the Inbox is to display a scrollable list of email messages, so it makes sense to offer the closely related compose action in a toolbar button at the top of the view." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Sidebars" + }, + { + "type": "paragraph", + "text": "Tab bars" + }, + { + "type": "paragraph", + "text": "Layout" + }, + { + "type": "paragraph", + "text": "Buttons" + }, + { + "type": "paragraph", + "text": "Search fields" + }, + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Toolbars — SwiftUI" + }, + { + "type": "paragraph", + "text": "UIToolbar — UIKit" + }, + { + "type": "paragraph", + "text": "NSToolbar — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 16, 2025", + "Updated guidance for Liquid Glass." + ], + [ + "June 9, 2025", + "Added guidance for grouping bar items, updated guidance for using symbols, and incorporated navigation bar guidance." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "June 5, 2023", + "Updated guidance for using toolbars in watchOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "search fields", + "url": "/design/human-interface-guidelines/search-fields" + }, + { + "title": "buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "menus", + "url": "/design/human-interface-guidelines/menus" + }, + { + "title": "tab bar", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/toolbars#Best-practices" + }, + { + "title": "Liquid Glass color", + "url": "/design/human-interface-guidelines/color#Liquid-Glass-color" + }, + { + "title": "Going full screen", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Titles", + "url": "/design/human-interface-guidelines/toolbars#Titles" + }, + { + "title": "Navigation", + "url": "/design/human-interface-guidelines/toolbars#Navigation" + }, + { + "title": "Icons", + "url": "/design/human-interface-guidelines/icons" + }, + { + "title": "Actions", + "url": "/design/human-interface-guidelines/toolbars#Actions" + }, + { + "title": "Standard icons", + "url": "/design/human-interface-guidelines/icons#Standard-icons" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Item groupings", + "url": "/design/human-interface-guidelines/toolbars#Item-groupings" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/toolbars#Platform-considerations" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/toolbars#iOS" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/toolbars#iPadOS" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "Windows", + "url": "/design/human-interface-guidelines/windows" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/toolbars#macOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/toolbars#visionOS" + }, + { + "title": "Pull-down buttons", + "url": "/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/toolbars#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/toolbars#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/toolbars#Related" + }, + { + "title": "Sidebars", + "url": "/design/human-interface-guidelines/sidebars" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/toolbars#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/toolbars#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/toolbars#Change-log" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/data/categories/getting-started.json b/data/categories/getting-started.json new file mode 100644 index 0000000..28eb451 --- /dev/null +++ b/data/categories/getting-started.json @@ -0,0 +1,1534 @@ +{ + "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": "getting-started" + }, + "name": "Getting Started", + "articles": [ + { + "title": "Designing for games", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-games", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you create or adapt a game for Apple platforms, learn how to integrate the fundamental platform characteristics and patterns that help your game feel at home on all Apple devices. To learn what makes each platform unique, see Designing for iOS, Designing for iPadOS, Designing for macOS, Designing for tvOS, Designing for visionOS, and Designing for watchOS. For developer guidance, see Games Pathway." + } + ] + }, + { + "heading": "Jump into gameplay", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people play as soon as installation completes. You don’t want a player’s first experience with your game to be waiting for a lengthy download. Include as much playable content as you can in your game’s initial installation while keeping the download time to 30 minutes or less. Download additional content in the background. For guidance, see Loading." + }, + { + "type": "paragraph", + "text": "Provide great default settings. People appreciate being able to start playing without first having to change a lot of settings. Use information about a player’s device to choose the best defaults for your game, such as the device resolution that makes your graphics look great, automatic recognition of paired accessories and game controllers, and the player’s accessibility settings. Also, make sure your game supports the platform’s most common interaction methods. For guidance, see Settings." + }, + { + "type": "paragraph", + "text": "Teach through play. Players often learn better when they discover new information and mechanics in the context of your game’s world, so it can work well to integrate configuration and onboarding flows into a playable tutorial that engages people quickly and helps them feel successful right away. If you also have a written tutorial, consider offering it as a resource players can refer to when they have questions instead of making it a prerequisite for gameplay. For guidance, see Onboarding." + }, + { + "type": "paragraph", + "text": "Defer requests until the right time. You don’t want to bombard people with too many requests before they start playing, but if your game uses certain sensors on an Apple device or personalizes gameplay by accessing data like hand-tracking, you must first get the player’s permission (for guidance, see Privacy). To help people understand why you’re making such a request, integrate it into the scenario that requires the data. For example, you could ask permission to track a player’s hands between an initial cutscene and the first time they can use their hands to control the action. Also, make sure people spend quality time with your game before you ask them for a rating or review (for guidance, see Ratings and reviews)." + } + ] + }, + { + "heading": "Look stunning on every display", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make sure text is always legible. When game text is hard to read, people can struggle to follow the narrative, understand important instructions and information, and stay engaged in the experience. To keep text comfortably legible on each device, ensure that it contrasts well with the background and uses at least the recommended minimum text size in each platform. For guidance, see Typography; for developer guidance, see Adapting your game interface for smaller screens." + }, + { + "type": "table", + "rows": [ + [ + "Platform", + "Default text size", + "Minimum text 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": "Make sure buttons are always easy to use. Buttons that are too small or too close together can frustrate players and make gameplay less fun. Each platform defines a recommended minimum button size based on its default interaction method. For example, buttons in iOS must be at least 44x44 pt to accommodate touch interaction. For guidance, see Buttons." + }, + { + "type": "table", + "rows": [ + [ + "Platform", + "Default button size", + "Minimum button 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": "Prefer resolution-independent textures and graphics. If creating resolution-independent assets isn’t possible, match the resolution of your game to the resolution of the device. In visionOS, prefer vector-based art that can continue to look good when the system dynamically scales it as people view it from different distances and angles. For guidance, see Images." + }, + { + "type": "paragraph", + "text": "Integrate device features into your layout. For example, a device may have rounded corners or a camera housing that can affect parts of your interface. To help your game look at home on each device, accommodate such features during layout, relying on platform-provided safe areas when possible (for developer guidance, see Positioning content relative to the safe area). For guidance, see Layout; for templates that include safe-area guides, see Apple Design Resources." + }, + { + "type": "paragraph", + "text": "Make sure in-game menus adapt to different aspect ratios. Games need to look good and behave well at various aspect ratios, such as 16:10, 19.5:9, and 4:3. In particular, in-game menus need to remain legible and easy to use on every device — and, if you support them, in both orientations on iPhone and iPad — without obscuring other content. To help ensure your in-game menus render correctly, consider using dynamic layouts that rely on relative constraints to adjust to different contexts. Avoid fixed layouts as much as possible, and aim to create a custom, device-specific layout only when necessary. For guidance, see In-game menus." + }, + { + "type": "paragraph", + "text": "Design for the full-screen experience. People often enjoy playing a game in a distraction-free, full-screen context. In macOS, iOS, and iPadOS, full-screen mode lets people hide other apps and parts of the system UI; in visionOS, a game running in a Full Space can completely surround people, transporting them somewhere else. For guidance, see Going full screen." + } + ] + }, + { + "heading": "Enable intuitive interactions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support each platform’s default interaction method. For example, people generally use touch to play games on iPhone; on a Mac, players tend to expect keyboard and mouse or trackpad support; and in a visionOS game, people expect to use their eyes and hands while making indirect and direct gestures. As you work to ensure that your game supports each platform’s default interaction method, pay special attention to control sizing and menu behavior, especially when bringing your game from a pointer-based context to a touch-based one." + }, + { + "type": "table", + "rows": [ + [ + "Platform", + "Default interaction methods", + "Additional interaction methods" + ], + [ + "iOS", + "Touch", + "Game controller" + ], + [ + "iPadOS", + "Touch", + "Game controller, keyboard, mouse, trackpad, Apple Pencil" + ], + [ + "macOS", + "Keyboard, mouse, trackpad", + "Game controller" + ], + [ + "tvOS", + "Remote", + "Game controller, keyboard, mouse, trackpad" + ], + [ + "visionOS", + "Touch", + "Game controller, keyboard, mouse, trackpad, spatial game controller" + ], + [ + "watchOS", + "Touch", + "–" + ] + ] + }, + { + "type": "paragraph", + "text": "Support physical game controllers, while also giving people alternatives. Every platform except watchOS supports physical game controllers. Although the presence of a game controller makes it straightforward to port controls from an existing game and handle complex control mappings, recognize that not every player can use a physical game controller. To make your game available to as many players as possible, also offer alternative ways to interact with your game. For guidance, see Physical controllers." + }, + { + "type": "paragraph", + "text": "Offer touch-based game controls that embrace the touchscreen experience on iPhone and iPad. In iOS and iPadOS, your game can allow players to interact directly with game elements, and to control the game using virtual controls that appear on top of your game content. For design guidance, see Touch controls." + } + ] + }, + { + "heading": "Welcome everyone", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prioritize perceivability. Make sure people can perceive your game’s content whether they use sight, hearing, or touch. For example, avoid relying solely on color to convey an important detail, or providing a cutscene that doesn’t include descriptive subtitles or offer other ways to read the content. For specific guidance, see:" + }, + { + "type": "list", + "items": [ + "Text sizes", + "Color and effects", + "Motion", + "Interactions", + "Buttons" + ] + }, + { + "type": "paragraph", + "text": "Help players personalize their experience. Players have a variety of preferences and abilities that influence their interactions with your game. Because there’s no universal configuration that suits everyone, give players the ability to customize parameters like type size, game control mapping, motion intensity, and sound balance. You can take advantage of built-in Apple accessibility technologies to support accessibility personalizations, whether you’re using system frameworks or Unity plug-ins." + }, + { + "type": "paragraph", + "text": "Give players the tools they need to represent themselves. If your game encourages players to create avatars or supply names or descriptions, support the spectrum of self-identity and provide options that represent as many human characteristics as possible." + }, + { + "type": "paragraph", + "text": "Avoid stereotypes in your stories and characters. Ask yourself whether you’re depicting game characters and scenarios in a way that perpetuates real-life stereotypes. For example, does your game depict enemies as having a certain race, gender, or cultural heritage? Review your game to uncover and remove biases and stereotypes and — if references to real-life cultures and languages are necessary — be sure they’re respectful." + } + ] + }, + { + "heading": "Adopt Apple technologies", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Integrate Game Center to help players discover your game across their devices and connect with their friends. Game Center is Apple’s social gaming network, available on all platforms. Game Center lets players keep track of their progress and achievements and allows you to set up leaderboards, challenges, and multiplayer activities in your game. For design guidance, see Game Center; for developer guidance, see GameKit." + }, + { + "type": "paragraph", + "text": "Let players pick up their game on any of their devices. People often have a single iCloud account that they use across multiple Apple devices. When you support GameSave, you can help people save their game state and start back up exactly where they left off on a different device." + }, + { + "type": "paragraph", + "text": "Support haptics to help players feel the action. When you adopt Core Haptics, you can compose and play custom haptic patterns, optionally combined with custom audio content. Core Haptics is available in iOS, iPadOS, tvOS, and visionOS, and supported on many game controllers. For guidance, see Playing haptics; for developer guidance, see Core Haptics and Playing Haptics on Game Controllers." + }, + { + "type": "paragraph", + "text": "Use Spatial Audio to immerse players in your game’s soundscape. Providing multichannel audio can help your game’s audio adapt automatically to the current device, enabling an immersive Spatial Audio experience where supported. For guidance, see Playing audio > visionOS; for developer guidance, see Explore Spatial Audio." + }, + { + "type": "paragraph", + "text": "Take advantage of Apple technologies to enable unique gameplay mechanics. For example, you can integrate technologies like augmented reality, machine learning, and HealthKit, and request access to location data and functionality like camera and microphone. For a full list of Apple technologies, features, and services, see Technologies." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Game Center" + }, + { + "type": "paragraph", + "text": "Game controls" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Games Pathway" + }, + { + "type": "paragraph", + "text": "Create games for Apple platforms" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated guidance for touch-based controls and Game Center." + ], + [ + "June 10, 2024", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "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": "Jump into gameplay", + "url": "/design/human-interface-guidelines/designing-for-games#Jump-into-gameplay" + }, + { + "title": "Loading", + "url": "/design/human-interface-guidelines/loading" + }, + { + "title": "Settings", + "url": "/design/human-interface-guidelines/settings" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/privacy" + }, + { + "title": "Ratings and reviews", + "url": "/design/human-interface-guidelines/ratings-and-reviews" + }, + { + "title": "Launching", + "url": "/design/human-interface-guidelines/launching" + }, + { + "title": "Look stunning on every display", + "url": "/design/human-interface-guidelines/designing-for-games#Look-stunning-on-every-display" + }, + { + "title": "Typography", + "url": "/design/human-interface-guidelines/typography" + }, + { + "title": "Buttons", + "url": "/design/human-interface-guidelines/buttons" + }, + { + "title": "Images", + "url": "/design/human-interface-guidelines/images" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "In-game menus", + "url": "/design/human-interface-guidelines/menus#In-game-menus" + }, + { + "title": "Going full screen", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "Enable intuitive interactions", + "url": "/design/human-interface-guidelines/designing-for-games#Enable-intuitive-interactions" + }, + { + "title": "Physical controllers", + "url": "/design/human-interface-guidelines/game-controls#Physical-controllers" + }, + { + "title": "Touch controls", + "url": "/design/human-interface-guidelines/game-controls#Touch-controls" + }, + { + "title": "Game controls", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Welcome everyone", + "url": "/design/human-interface-guidelines/designing-for-games#Welcome-everyone" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Inclusion", + "url": "/design/human-interface-guidelines/inclusion" + }, + { + "title": "Adopt Apple technologies", + "url": "/design/human-interface-guidelines/designing-for-games#Adopt-Apple-technologies" + }, + { + "title": "Game Center", + "url": "/design/human-interface-guidelines/game-center" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Playing audio > visionOS", + "url": "/design/human-interface-guidelines/playing-audio#visionOS" + }, + { + "title": "Technologies", + "url": "/design/human-interface-guidelines/technologies" + }, + { + "title": "iCloud", + "url": "/design/human-interface-guidelines/icloud" + }, + { + "title": "In-app purchase", + "url": "/design/human-interface-guidelines/in-app-purchase" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-games#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-games#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-games#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-games#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/designing-for-games#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Designing for iOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-ios", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app or game for iOS, start by understanding the following fundamental device characteristics and patterns that distinguish the iOS experience. Using these characteristics and patterns to inform your design decisions can help you provide an app or game that iPhone users appreciate." + }, + { + "type": "paragraph", + "text": "Display. iPhone has a medium-size, high-resolution display." + }, + { + "type": "paragraph", + "text": "Ergonomics. People generally hold their iPhone in one or both hands as they interact with it, switching between landscape and portrait orientations as needed. While people are interacting with the device, their viewing distance tends to be no more than a foot or two." + }, + { + "type": "paragraph", + "text": "Inputs. Multi-Touch gestures, virtual keyboards, and voice control let people perform actions and accomplish meaningful tasks while they’re on the go. In addition, people often want apps to use their personal data and input from the device’s gyroscope and accelerometer, and they may also want to participate in spatial interactions." + }, + { + "type": "paragraph", + "text": "App interactions. Sometimes, people spend just a minute or two checking on event or social media updates, tracking data, or sending messages. At other times, people can spend an hour or more browsing the web, playing games, or enjoying media. People typically have multiple apps open at the same time, and they appreciate switching frequently among them." + }, + { + "type": "paragraph", + "text": "System features. iOS provides several features that help people interact with the system and their apps in familiar, consistent ways." + }, + { + "type": "list", + "items": [ + "Widgets", + "Home Screen quick actions", + "Spotlight", + "Shortcuts", + "Activity views" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great iPhone experiences integrate the platform and device capabilities that people value most. To help your design feel at home in iOS, prioritize the following ways to incorporate these features and capabilities." + }, + { + "type": "list", + "items": [ + "Help people concentrate on primary tasks and content by limiting the number of onscreen controls while making secondary details and actions discoverable with minimal interaction.", + "Adapt seamlessly to appearance changes — like device orientation, Dark Mode, and Dynamic Type — letting people choose the configurations that work best for them.", + "Support interactions that accommodate the way people usually hold their device. For example, it tends to be easier and more comfortable for people to reach a control when it’s located in the middle or bottom area of the display, so it’s especially important let people swipe to navigate back or initiate actions in a list row.", + "With people’s permission, integrate information available through platform capabilities in ways that enhance the experience without asking people to enter data. For example, you might accept payments, provide security through biometric authentication, or offer features that use the device’s location." + ] + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "iOS Pathway" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "gestures", + "url": "https://developer.apple.com/design/human-interface-guidelines/gestures" + }, + { + "title": "virtual keyboards", + "url": "https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards" + }, + { + "title": "voice", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri" + }, + { + "title": "personal data", + "url": "https://developer.apple.com/design/human-interface-guidelines/privacy" + }, + { + "title": "gyroscope and accelerometer", + "url": "https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer" + }, + { + "title": "spatial interactions", + "url": "https://developer.apple.com/design/human-interface-guidelines/spatial-interactions" + }, + { + "title": "Widgets", + "url": "/design/human-interface-guidelines/widgets" + }, + { + "title": "Home Screen quick actions", + "url": "/design/human-interface-guidelines/home-screen-quick-actions" + }, + { + "title": "Spotlight", + "url": "https://developer.apple.com/design/human-interface-guidelines/searching" + }, + { + "title": "Shortcuts", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" + }, + { + "title": "Activity views", + "url": "/design/human-interface-guidelines/activity-views" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-ios#Best-practices" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-ios#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-ios#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-ios#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-ios#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Designing for iPadOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-ipados", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app or game for iPad, start by understanding the following fundamental device characteristics and patterns that distinguish the iPadOS experience. Using these characteristics and patterns to inform your design decisions can help you provide an app or game that iPad users appreciate." + }, + { + "type": "paragraph", + "text": "Display. iPad has a large, high-resolution display." + }, + { + "type": "paragraph", + "text": "Ergonomics. People often hold their iPad while using it, but they might also set it on a surface or place it on a stand. Positioning the device in different ways can change the viewing distance, although people are typically within about 3 feet of the device as they interact with it." + }, + { + "type": "paragraph", + "text": "Inputs. People can interact with iPad using Multi-Touch gestures and virtual keyboards, an attached keyboard or pointing device, Apple Pencil, or voice, and they often combine multiple input modes." + }, + { + "type": "paragraph", + "text": "App interactions. Sometimes, people perform a few quick actions on their iPad. At other times, they spend hours immersed in games, media, content creation, or productivity tasks. People frequently have multiple apps open at the same time, and they appreciate viewing more than one app onscreen at once and taking advantage of inter-app capabilities like drag and drop." + }, + { + "type": "paragraph", + "text": "System features. iPadOS provides several features that help people interact with the system and their apps in familiar, consistent ways." + }, + { + "type": "list", + "items": [ + "Multitasking", + "Widgets", + "Drag and drop" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great iPad experiences integrate the platform and device capabilities that people value most. To help your experience feel at home in iPadOS, prioritize the following ways to incorporate these features and capabilities." + }, + { + "type": "list", + "items": [ + "Take advantage of the large display to elevate the content people care about, minimizing modal interfaces and full-screen transitions, and positioning onscreen controls where they’re easy to reach, but not in the way.", + "Use viewing distance and input mode to help you determine the size and density of the onscreen content you display.", + "Let people use Multi-Touch gestures, a physical keyboard or trackpad, or Apple Pencil, and consider supporting unique interactions that combine multiple input modes.", + "Adapt seamlessly to appearance changes — like device orientation, multitasking modes, Dark Mode, and Dynamic Type — and transition effortlessly to running in macOS, letting people choose the configurations that work best for them." + ] + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "iPadOS Pathway" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "gestures", + "url": "https://developer.apple.com/design/human-interface-guidelines/gestures" + }, + { + "title": "virtual keyboards", + "url": "https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards" + }, + { + "title": "keyboard", + "url": "https://developer.apple.com/design/human-interface-guidelines/keyboards" + }, + { + "title": "pointing device", + "url": "https://developer.apple.com/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Apple Pencil", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble" + }, + { + "title": "voice", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri" + }, + { + "title": "Multitasking", + "url": "/design/human-interface-guidelines/multitasking" + }, + { + "title": "Widgets", + "url": "/design/human-interface-guidelines/widgets" + }, + { + "title": "Drag and drop", + "url": "/design/human-interface-guidelines/drag-and-drop" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-ipados#Best-practices" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-ipados#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-ipados#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-ipados#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-ipados#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Designing for macOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-macos", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app or game for macOS, start by understanding the fundamental device characteristics and patterns that distinguish the macOS experience. Using these characteristics and patterns to inform your design decisions can help you provide an app or game that Mac users appreciate." + }, + { + "type": "paragraph", + "text": "Display. A Mac typically has a large, high-resolution display, and people can extend their workspace by connecting additional displays, including their iPad." + }, + { + "type": "paragraph", + "text": "Ergonomics. People generally use a Mac while they’re stationary, often placing the device on a desk or table. In the typical use case, the viewing distance can range from about 1 to 3 feet." + }, + { + "type": "paragraph", + "text": "Inputs. People expect to enter data and control the interface using any combination of input modes, such as physical Keyboards, Pointing devices, Game controls, and Siri." + }, + { + "type": "paragraph", + "text": "App interactions. Interactions can last anywhere from a few minutes of performing some quick tasks to several hours of deep concentration. People frequently have multiple apps open at the same time, and they expect smooth transitions between active and inactive states as they switch from one app to another." + }, + { + "type": "paragraph", + "text": "System features. macOS provides several features that help people interact with the system and their apps in familiar, consistent ways." + }, + { + "type": "list", + "items": [ + "The menu bar", + "File management", + "Going full screen", + "Dock menus" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great Mac experiences integrate the platform and device capabilities that people value most. To help your design feel at home in macOS, prioritize the following ways to incorporate these features and capabilities." + }, + { + "type": "list", + "items": [ + "Leverage large displays to present more content in fewer nested levels and with less need for modality, while maintaining a comfortable information density that doesn’t make people strain to view the content they want.", + "Let people resize, hide, show, and move your windows to fit their work style and device configuration, and support full-screen mode to offer a distraction-free context.", + "Use the menu bar to give people easy access to all the commands they need to do things in your app.", + "Help people take advantage of high-precision input modes to perform pixel-perfect selections and edits.", + "Handle keyboard shortcuts to help people accelerate actions and use keyboard-only work styles.", + "Support personalization, letting people customize toolbars, configure windows to display the views they use most, and choose the colors and fonts they want to see in the interface." + ] + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "macOS Pathway" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Game controls", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "Siri", + "url": "/design/human-interface-guidelines/siri" + }, + { + "title": "The menu bar", + "url": "/design/human-interface-guidelines/the-menu-bar" + }, + { + "title": "File management", + "url": "/design/human-interface-guidelines/file-management" + }, + { + "title": "Going full screen", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "Dock menus", + "url": "/design/human-interface-guidelines/dock-menus" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-macos#Best-practices" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-macos#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-macos#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-macos#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-macos#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Designing for tvOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-tvos", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app or game for tvOS, start by understanding the following fundamental device characteristics and patterns that distinguish the tvOS experience. Using these characteristics and patterns to inform your design decisions can help you provide an app or game that tvOS users appreciate." + }, + { + "type": "paragraph", + "text": "Display. A TV typically has a very large, high-resolution display." + }, + { + "type": "paragraph", + "text": "Ergonomics. Although people generally remain many feet away from their stationary TV — often 8 feet or more — they sometimes continue to interact with content as they move around the room." + }, + { + "type": "paragraph", + "text": "Inputs. People can use a remote, a game controller, their voice, and apps running on their other devices to interact with Apple TV." + }, + { + "type": "paragraph", + "text": "App interactions. People can get deeply immersed in a single experience — often lasting hours — but they also appreciate using a picture-in-picture view to simultaneously follow an alternative app or video." + }, + { + "type": "paragraph", + "text": "System features. Apple TV users expect their apps and games to integrate well with the following system experiences." + }, + { + "type": "list", + "items": [ + "Integrating with the TV app", + "SharePlay", + "Top Shelf", + "TV provider accounts" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great tvOS experiences integrate the platform and device capabilities that people value most. To help your experience feel at home in tvOS, prioritize the following ways to incorporate these features and capabilities." + }, + { + "type": "list", + "items": [ + "Support powerful, delightful interactions through the fluid, familiar gestures people make with the Siri Remote.", + "Embrace the tvOS focus system, letting it gently highlight and expand onscreen items as people move among them, helping them know what to do and where they are at all times.", + "Deliver beautiful, edge-to-edge artwork, subtle and fluid animations, and engaging audio, wrapping people in a rich, cinematic experience that’s clear, legible, and captivating from across the room.", + "Enhance multiuser support by making sign-in easy and infrequent, handling shared sign-in, and automatically switching profiles when people change the current viewer." + ] + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "tvOS Pathway" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 14, 2022", + "Refined best practices for multiuser support." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "remote", + "url": "https://developer.apple.com/design/human-interface-guidelines/remotes" + }, + { + "title": "game controller", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-controls" + }, + { + "title": "voice", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri" + }, + { + "title": "Integrating with the TV app", + "url": "/design/human-interface-guidelines/playing-video#Integrating-with-the-TV-app" + }, + { + "title": "SharePlay", + "url": "/design/human-interface-guidelines/shareplay" + }, + { + "title": "Top Shelf", + "url": "/design/human-interface-guidelines/top-shelf" + }, + { + "title": "TV provider accounts", + "url": "/design/human-interface-guidelines/managing-accounts#TV-provider-accounts" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-tvos#Best-practices" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-tvos#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-tvos#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-tvos#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-tvos#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/designing-for-tvos#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Designing for visionOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app or game for visionOS, start by understanding the fundamental device characteristics and patterns that distinguish the platform. Use these characteristics and patterns to inform your design decisions and help you create immersive and engaging experiences." + }, + { + "type": "paragraph", + "text": "Space. Apple Vision Pro offers a limitless canvas where people can view virtual content like windows, volumes, and 3D objects, and choose to enter deeply immersive experiences that can transport them to different places." + }, + { + "type": "paragraph", + "text": "Immersion. In a visionOS app, people can fluidly transition between different levels of immersion. By default, an app launches in the Shared Space where multiple apps can run side-by-side and people can open, close, and relocate windows. People can also choose to transition an app to a Full Space, where it’s the only app running. While in a Full Space app, people can view 3D content blended with their surroundings, open a portal to view another place, or enter a different world." + }, + { + "type": "paragraph", + "text": "Passthrough. Passthrough provides live video from the device’s external cameras, and helps people interact with virtual content while also seeing their actual surroundings. When people want to see more or less of their surroundings, they use the Digital Crown to control the amount of passthrough." + }, + { + "type": "paragraph", + "text": "Spatial Audio. Apple Vision Pro combines acoustic and visual-sensing technologies to model the sonic characteristics of a person’s surroundings, automatically making audio sound natural in their space. When an app receives a person’s permission to access information about their surroundings, it can fine-tune Spatial Audio to bring custom experiences to life." + }, + { + "type": "paragraph", + "text": "Eyes and hands. In general, people perform most actions by using their eyes to look at a virtual object and making an indirect gesture, like a tap, to activate it. People can also interact with a virtual object by using a direct gesture, like touching it with a finger." + }, + { + "type": "paragraph", + "text": "Ergonomics. While wearing Apple Vision Pro, people rely entirely on the device’s cameras for everything they see, both real and virtual, so maintaining visual comfort is paramount. The system helps maintain comfort by automatically placing content so it’s relative to the wearer’s head, regardless of the person’s height or whether they’re sitting, standing, or lying down. Because visionOS brings content to people — instead of making people move to reach the content — people can remain at rest while engaging with apps and games." + }, + { + "type": "paragraph", + "text": "Accessibility. Apple Vision Pro supports accessibility technologies like VoiceOver, Switch Control, Dwell Control, Guided Access, Head Pointer, and many more, so people can use the interactions that work for them. In visionOS, as in all platforms, system-provided UI components build in accessibility support by default, while system frameworks give you ways to enhance the accessibility of your app or game." + }, + { + "type": "important", + "text": "ImportantWhen building your app for Apple Vision Pro, be sure to consider the unique characteristics of the device and its spatial computing environment, and pay special attention to your user’s safety; for more details about these characteristics, see Apple Vision Pro User Guide. For example, Apple Vision Pro should not be used while operating a vehicle or heavy machinery. The device is also not designed to be used while moving around unsafe environments such as near balconies, streets, stairs, or other potential hazards. Note that Apple Vision Pro is designed to be fit and used only by individuals 13 years of age or older." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great visionOS apps and games are approachable and familiar, while offering extraordinary experiences that can surround people with beautiful content, expanded capabilities, and captivating adventures." + }, + { + "type": "paragraph", + "text": "Embrace the unique features of Apple Vision Pro. Take advantage of space, Spatial Audio, and immersion to bring life to your experiences, while integrating passthrough and spatial input from eyes and hands in ways that feel at home on the device." + }, + { + "type": "paragraph", + "text": "Consider different types of immersion as you design ways to present your app’s most distinctive moments. You can present experiences in a windowed, UI-centric context, a fully immersive context, or something in between. For each key moment in your app, find the minimum level of immersion that suits it best — don’t assume that every moment needs to be fully immersive." + }, + { + "type": "paragraph", + "text": "Use windows for contained, UI-centric experiences. To help people perform standard tasks, prefer standard windows that appear as planes in space and contain familiar controls. In visionOS, people can relocate windows anywhere they want, and the system’s dynamic scaling helps keep window content legible whether it’s near or far." + }, + { + "type": "paragraph", + "text": "Prioritize comfort. To help people stay comfortable and physically relaxed as they interact with your app or game, keep the following fundamentals in mind." + }, + { + "type": "list", + "items": [ + "Display content within a person’s field of view, positioning it relative to their head. Avoid placing content in places where people have to turn their head or change their position to interact with it.", + "Avoid displaying motion that’s overwhelming, jarring, too fast, or missing a stationary frame of reference.", + "Support indirect gestures that let people interact with apps while their hands rest in their lap or at their sides.", + "If you support direct gestures, make sure the interactive content isn’t too far away and that people don’t need to interact with it for extended periods.", + "Avoid encouraging people to move too much while they’re in a fully immersive experience." + ] + }, + { + "type": "paragraph", + "text": "Help people share activities with others. When you use SharePlay to support shared activities, people can view the spatial Personas of other participants, making it feel like everyone is together in the same space." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "visionOS Pathway" + }, + { + "type": "paragraph", + "text": "Creating your first visionOS app" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "February 2, 2024", + "Included a link to Apple Vision Pro User Guide." + ], + [ + "September 12, 2023", + "Updated intro artwork." + ], + [ + "June 21, 2023", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "windows", + "url": "/design/human-interface-guidelines/windows" + }, + { + "title": "volumes", + "url": "/design/human-interface-guidelines/windows#visionOS-volumes" + }, + { + "title": "immersion", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Passthrough", + "url": "/design/human-interface-guidelines/immersive-experiences#Immersion-and-passthrough" + }, + { + "title": "Digital Crown", + "url": "/design/human-interface-guidelines/digital-crown" + }, + { + "title": "Spatial Audio", + "url": "/design/human-interface-guidelines/playing-audio#visionOS" + }, + { + "title": "eyes", + "url": "/design/human-interface-guidelines/eyes" + }, + { + "title": "gesture", + "url": "/design/human-interface-guidelines/gestures#visionOS" + }, + { + "title": "accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-visionos#Best-practices" + }, + { + "title": "windows", + "url": "/design/human-interface-guidelines/windows#visionOS" + }, + { + "title": "dynamic scaling", + "url": "/design/human-interface-guidelines/spatial-layout#Scale" + }, + { + "title": "field of view", + "url": "/design/human-interface-guidelines/spatial-layout#Field-of-view" + }, + { + "title": "motion", + "url": "/design/human-interface-guidelines/motion#visionOS" + }, + { + "title": "SharePlay", + "url": "/design/human-interface-guidelines/shareplay#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-visionos#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-visionos#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-visionos#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-visionos#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/designing-for-visionos#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Designing for watchOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos", + "category": "getting-started", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As you begin designing your app for Apple Watch, start by understanding the following fundamental device characteristics and patterns that distinguish the watchOS experience. Using these characteristics and patterns to inform your design decisions can help you provide an app that Apple Watch users appreciate." + }, + { + "type": "paragraph", + "text": "Display. The small Apple Watch display fits on the wrist while delivering an easy-to-read, high-resolution experience." + }, + { + "type": "paragraph", + "text": "Ergonomics. Because people wear Apple Watch, they’re usually no more than a foot away from the display as they raise their wrist to view it and use their opposite hand to interact with the device. In addition, the Always On display lets people view information on the watch face when they drop their wrist." + }, + { + "type": "paragraph", + "text": "Inputs. People can navigate vertically or inspect data by turning the Digital Crown, which offers consistent control on the watch face, the Home Screen, and within apps. They can provide input even while they’re in motion with standard gestures like tap, swipe, and drag. Pressing the Action button initiates an essential action without looking at the screen, and using shortcuts helps people perform their routine tasks quickly and easily. People can also take advantage of data that device features provide, such as GPS, sensors for blood oxygen and heart function, and the altimeter, accelerometer, and gyroscope." + }, + { + "type": "paragraph", + "text": "App interactions. People glance at the Always On display many times throughout the day, performing concise app interactions that can last for less than a minute each. People frequently use a watchOS app’s related experiences — like complications, notifications, and Siri interactions — more than they use the app itself." + }, + { + "type": "paragraph", + "text": "System features. watchOS provides several features that help people interact with the system and their apps in familiar, consistent ways." + }, + { + "type": "list", + "items": [ + "Complications", + "Notifications", + "Always On", + "Watch faces" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Great Apple Watch experiences are streamlined and specialized, and integrate the platform and device capabilities that people value most. To help your experience feel at home in watchOS, prioritize the following ways to incorporate these features and capabilities." + }, + { + "type": "list", + "items": [ + "Support quick, glanceable, single-screen interactions that deliver critical information succinctly and help people perform targeted actions with a simple gesture or two.", + "Minimize the depth of hierarchy in your app’s navigation, and use the Digital Crown to provide vertical navigation for scrolling or switching between screens.", + "Personalize the experience by proactively anticipating people’s needs and using on-device data to provide actionable content that’s relevant in the moment or very soon.", + "Use complications to provide relevant, potentially dynamic data and graphics right on the watch face where people can view them on every wrist raise and tap them to dive straight into your app.", + "Use notifications to deliver timely, high-value information and let people perform important actions without opening your app.", + "Use background content such as color to convey useful supporting information, and use materials to illustrate hierarchy and a sense of place.", + "Design your app to function independently, complementing your notifications and complications by providing additional details and functionality." + ] + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "watchOS Pathway" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 5, 2023", + "Enhanced guidance for providing a glanceable, focused app experience, and emphasized the importance of the Digital Crown in navigation." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Digital Crown", + "url": "/design/human-interface-guidelines/digital-crown" + }, + { + "title": "gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Action button", + "url": "/design/human-interface-guidelines/action-button" + }, + { + "title": "shortcuts", + "url": "/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" + }, + { + "title": "Complications", + "url": "/design/human-interface-guidelines/complications" + }, + { + "title": "Notifications", + "url": "/design/human-interface-guidelines/notifications" + }, + { + "title": "Always On", + "url": "/design/human-interface-guidelines/always-on" + }, + { + "title": "Watch faces", + "url": "/design/human-interface-guidelines/watch-faces" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/designing-for-watchos#Best-practices" + }, + { + "title": "color", + "url": "/design/human-interface-guidelines/color" + }, + { + "title": "materials", + "url": "/design/human-interface-guidelines/materials" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/designing-for-watchos#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/designing-for-watchos#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/designing-for-watchos#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/designing-for-watchos#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/designing-for-watchos#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Getting started", + "url": "https://developer.apple.com/design/human-interface-guidelines/getting-started", + "category": "getting-started", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "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" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/data/categories/inputs.json b/data/categories/inputs.json new file mode 100644 index 0000000..cab120e --- /dev/null +++ b/data/categories/inputs.json @@ -0,0 +1,4476 @@ +{ + "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": "inputs" + }, + "name": "Inputs", + "articles": [ + { + "title": "Action button", + "url": "https://developer.apple.com/design/human-interface-guidelines/action-button", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On a supported device, people can use the Action button to run App Shortcuts or access system-provided functionality, like turning the flashlight on or off. On Apple Watch Ultra, the Action button supports activity-related actions, including workouts and dives." + }, + { + "type": "paragraph", + "text": "A person chooses a function for the Action button when they set up their device; later, they can adjust this choice in Settings. When someone associates an App Shortcut with the Action button, pressing the button runs the App Shortcut similarly to using their voice with Siri or tapping it in Spotlight." + }, + { + "type": "paragraph", + "text": "When designing your app or game, think of the Action button as another way for someone to quickly access a function that they use on a regular basis." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support the Action button with a set of your app’s essential functions. For example, if your cooking app includes an egg timer, a “Start Egg Timer” action might be one that people want to initiate when they press the Action button. You don’t need to offer an App Shortcut that opens your app, because the system provides this function already. Your app icon, widgets, and Apple Watch complications give people other quick ways to open your app. For additional guidance, see App Shortcuts." + }, + { + "type": "paragraph", + "text": "For each action you support, write a short label that succinctly describes it. People see your labels when they visit Settings to configure the Action button’s behavior. Create labels that use title-style capitalization, begin with a verb, use present tense, and exclude articles and prepositions. Keep labels as short as possible, with a maximum of three words. For example, use “Start Race” instead of “Started Race” or “Start the Race.”" + }, + { + "type": "paragraph", + "text": "Prefer letting the system show people how to use the Action button with your app. When you support the Action button, the system automatically helps people configure it to initiate one of your app’s functions. Avoid creating content that repeats the guidance offered in Settings for the Action button, or other usage tips the system provides." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Let people use your actions without leaving their current context. When possible, make use of lightweight multitasking capabilities like Live Activities and custom snippets to provide functionality without opening your app. For example, the “Set Timer” action doesn’t launch the Clock app; it prompts people to set a duration for the timer, and then launches a Live Activity with the countdown." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In watchOS, a person can assign the Action button’s first press to drop a waypoint, start a dive, or begin a specific workout. Beyond a single button press, the Action button also supports secondary actions like marking a segment or transitioning to the next modality during a multi-part workout." + }, + { + "type": "paragraph", + "text": "Consider offering a secondary function that supports or advances the primary action people choose. People often use the Action button without looking at the screen, so a subsequent button press needs to flow logically from the first press, while also making sense in the current context. If your app supports workout or dive actions, consider designing a simple, intuitive secondary function that people can easily learn and remember. Consider carefully before you offer more than one secondary function, because doing so can increase people’s cognitive load and make your app seem harder to use." + }, + { + "type": "paragraph", + "text": "Prefer using subsequent button presses to support additional functionality rather than to stop or conclude a function. If you need to let people stop their main task — as opposed to pausing the current function — offer this option within your interface instead." + }, + { + "type": "paragraph", + "text": "Pause the current function when people press the Action button and side button together. The exception is in a diving app where pausing a dive may be dangerous to the diver, causing them to lose track of their depth or not understand how long they’ve been underwater. Unless pausing the current function results in a negative experience, be sure to meet people’s expectations by letting them pause their current activity when they press both buttons at the same time." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Workouts" + }, + { + "type": "paragraph", + "text": "Digital Crown" + }, + { + "type": "paragraph", + "text": "App Shortcuts" + }, + { + "type": "paragraph", + "text": "Live Activities" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Updated to include guidance for iOS." + ], + [ + "September 14, 2022", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "App Shortcuts", + "url": "/design/human-interface-guidelines/app-shortcuts" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/action-button#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/action-button#Platform-considerations" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/action-button#iOS" + }, + { + "title": "Live Activities", + "url": "/design/human-interface-guidelines/live-activities" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/action-button#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/action-button#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/action-button#Related" + }, + { + "title": "Workouts", + "url": "/design/human-interface-guidelines/workouts" + }, + { + "title": "Digital Crown", + "url": "/design/human-interface-guidelines/digital-crown" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/action-button#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Apple Pencil and Scribble", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apple Pencil is a versatile, intuitive tool for iPad apps that offers pixel‑level precision when jotting notes, sketching, painting, marking up documents, and more. Scribble lets people use Apple Pencil to enter text in any text field through fast, private, on-device handwriting recognition." + }, + { + "type": "paragraph", + "text": "For details on Apple Pencil features and compatibility, see Apple Pencil." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support behaviors people intuitively expect when using a marking instrument. Most people have a lot of experience with real-world marking tools, and this knowledge informs their expectations when they use Apple Pencil with your app. To provide a delightful experience, think about the ways people interact with nondigital pencils, pens, and other marking instruments, and proactively support actions that people may naturally attempt. For example, people often want to write in the margins of documents or books." + }, + { + "type": "paragraph", + "text": "Let people choose when to switch between Apple Pencil and finger input. For example, if your app supports Apple Pencil for marking, also ensure that your app’s controls respond to Apple Pencil so people don’t have to switch to using their finger to activate them. In this scenario, a control that doesn’t support Apple Pencil input might seem to be unresponsive, giving the impression of a malfunction or low battery. (Scribble only supports Apple Pencil input.)" + }, + { + "type": "paragraph", + "text": "Let people make a mark the moment Apple Pencil touches the screen. You want the experience of putting Apple Pencil to screen to mirror the experience of putting a classic pencil to paper, so it’s essential to avoid requiring people to tap a button or enter a special mode before they can make a mark." + }, + { + "type": "paragraph", + "text": "Help people express themselves by responding to the way they use Apple Pencil. Apple Pencil may sense tilt (altitude), force (pressure), orientation (azimuth), and barrel roll. Use this information to affect the strokes Apple Pencil makes, such as by varying thickness and intensity. When responding to pressure, keep things simple and intuitive. For example, it feels natural to affect continuous properties — such as ink opacity or brush size — by varying the pressure." + }, + { + "type": "paragraph", + "text": "Altitude" + }, + { + "type": "paragraph", + "text": "Pressure" + }, + { + "type": "paragraph", + "text": "Azimuth" + }, + { + "type": "paragraph", + "text": "Provide visual feedback to indicate a direct connection with content. Make sure Apple Pencil appears to directly and immediately manipulate content it touches onscreen. Avoid letting Apple Pencil appear to initiate seemingly disconnected actions, or affect content on other parts of the screen." + }, + { + "type": "paragraph", + "text": "Design a great left- and right-handed experience. Avoid placing controls in locations that may be obscured by either hand. If there’s a chance controls may become obscured, consider letting people reposition them." + } + ] + }, + { + "heading": "Hover", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use hover to help people predict what will happen when Apple Pencil touches the screen. For example, as people hold Apple Pencil above the screen, a hover preview can show the dimensions and color of the mark that the current tool can make. As much as possible, avoid continuously modifying the preview as people move Apple Pencil closer or farther from the screen. A preview that changes according to height is unlikely to clarify the mark Apple Pencil will make, and frequent visual variations can be very distracting to people." + }, + { + "type": "paragraph", + "text": "Avoid using hover to initiate an action. Unlike tapping a button or marking the screen, hovering is a relatively imprecise motion that doesn’t require people to think about the actual distance between Apple Pencil and the display. You don’t want people to inadvertently perform an action — especially a destructive action that they might want to undo — just because they hold Apple Pencil near the screen." + }, + { + "type": "paragraph", + "text": "Prefer showing a preview value that’s near the middle in a range of dynamic values. Dynamic properties like opacity or flow can be difficult to depict at the highest or lowest ends of the spectrum. For example, previewing the appearance of a brush mark made with the maximum pressure could occlude the area in which people are marking; in contrast, depicting a mark made with the minimum pressure could be hard for people to detect, making the preview an inaccurate representation of an actual mark or even invisible." + }, + { + "type": "paragraph", + "text": "Consider using hover to support relevant interactions close to where people are marking. For example, you might respond to hover by displaying a contextual menu of tool sizes when people perform a gesture like squeeze or press a modifier key on an attached keyboard. Revealing a menu near where people are marking lets them make choices without moving Apple Pencil or their hands to another part of the screen." + }, + { + "type": "paragraph", + "text": "Prefer showing hover previews for Apple Pencil, not for a pointing device. Although a pointing device can also respond to hover gestures, it might be confusing to provide the same visual feedback for both devices. If it makes sense in your app, you can restrict your hover preview to Apple Pencil only. For developer guidance, see Adopting hover support for Apple Pencil." + } + ] + }, + { + "heading": "Double tap", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Respect people’s settings for the double-tap gesture when they make sense in your app. By default, models of Apple Pencil that support the double-tap gesture respond by toggling between the current tool and the eraser, but people can set the gesture to toggle between the current and previous tool, show and hide the color picker, or do nothing at all. If your app supports these behaviors, let people use their preferred gestures to perform them. If the systemwide double-tap settings don’t make sense in your app, you can still use the gesture to change the interaction mode. For example, a 3D app that offers a mesh-editing tool could use double tap to toggle between the tool’s raise and lower modes." + }, + { + "type": "paragraph", + "text": "Give people a way to specify custom double-tap behavior if necessary. If you offer custom double-tap behavior in addition to some or all of the default behaviors, provide a control that lets people choose the custom behavior mode. People need to know which mode they’re in; otherwise, they may get confused when your app responds differently to their interactions. In this scenario, make sure it’s easy for people to discover the custom behavior your app supports, but don’t turn it on by default." + }, + { + "type": "paragraph", + "text": "Avoid using the double-tap gesture to perform an action that modifies content. In rare cases, it’s possible for people to double-tap accidentally, which means that they may not even be aware that your app has performed the action. Prefer using double tap to perform actions that are easy for people to undo. In particular, avoid using double tap to perform a potentially destructive action that might result in data loss." + } + ] + }, + { + "heading": "Squeeze", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Using Apple Pencil Pro, people can squeeze to perform an action. You can design a custom behavior that responds to squeeze, but recognize that people may choose to configure the squeeze gesture to run an App Shortcut instead of app-specific actions." + }, + { + "type": "note", + "text": "NoteThe squeeze gesture is available only when the paired iPad screen is on and while the Apple Pencil Pro is not directly contacting it. Because squeeze works when there’s distance between Apple Pencil Pro and iPad, people might not always be visually aware of the gesture’s onscreen result." + }, + { + "type": "paragraph", + "text": "Treat squeeze as a single, quick gesture that performs a discrete — not continuous — action. People sometimes squeeze with a lot of force, so holding a squeeze or squeezing several times quickly can be tiring. Help people remain comfortable by responding to a single squeeze and promptly displaying the result." + }, + { + "type": "paragraph", + "text": "If you use squeeze to reveal app UI, like a contextual menu, display it close to Apple Pencil Pro. Displaying the result of a squeeze near the tip of Apple Pencil Pro strengthens the connection between the device and the gesture, and can help people stay engaged with their task." + }, + { + "type": "paragraph", + "text": "Define squeeze actions that are nondestructive and easy to undo. As with the double-tap gesture, people can make the squeeze gesture without meaning to, so it’s essential to avoid using squeeze to perform an action that could result in data loss." + } + ] + }, + { + "heading": "Barrel roll", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "While marking with Apple Pencil Pro, people can use a barrel-roll gesture to change the type of mark they’re making. For example, while using Apple Pencil Pro to highlight content in Notes, people can barrel-roll to rotate the angle of the mark." + }, + { + "type": "paragraph", + "text": "Use barrel roll only to modify marking behavior, not to enable navigation or display other controls. In contrast to double tap and squeeze, barrel roll is naturally related to marking and doesn’t make sense for performing an interface action." + } + ] + }, + { + "heading": "Scribble", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "With Scribble and Apple Pencil, people can simply write wherever text is accepted in your app — they don’t have to tap or switch modes first. Because Scribble is fully integrated into iPadOS, it’s available to all apps by default." + }, + { + "type": "paragraph", + "text": "Make text entry feel fluid and effortless. By default, Scribble works in all standard text components — such as text fields, text views, search fields, and editable fields in web content — except password fields. If you use a custom text field in your app, avoid making people tap or select it before they can begin writing." + }, + { + "type": "paragraph", + "text": "Make Scribble available everywhere people might want to enter text. Unlike using the keyboard, using Apple Pencil encourages people to treat the screen the way they treat a sheet of paper. Help strengthen this perception in your app by making Scribble consistently available in places where text entry seems natural. For example, in Reminders, it’s natural for people to create a new reminder by writing it in the blank space below the last item, even though the area doesn’t contain a text field. For developer guidance, see UIIndirectScribbleInteraction." + }, + { + "type": "paragraph", + "text": "Avoid distracting people while they write. Some text field behaviors work well for keyboard input, but can disrupt the natural writing experience that Apple Pencil provides. For example, it’s best to avoid displaying autocompletion text as people write in a text field because the suggestions can visually interfere with their writing. It’s also a good idea to hide a field’s placeholder text the moment people begin to write so that their input doesn’t appear to overlap it." + }, + { + "type": "paragraph", + "text": "While people are writing in a text field, make sure it remains stationary. In some cases, it can make sense to move a text field when it becomes focused: for example, a search field might move to make more room to display results. Such a movement is fine when people are using the keyboard, but when they’re writing it can make them feel like they’ve lost control of where their input is going. If you can’t prevent a text field from moving or resizing, consider delaying the change until people pause their writing." + }, + { + "type": "paragraph", + "text": "Prevent autoscrolling text while people are writing and editing in a text field. When transcribed text autoscrolls, people might try to avoid writing on top of it. Worse, if text scrolls while people are using Apple Pencil to select it, they might select a different range of text than they want." + }, + { + "type": "paragraph", + "text": "Give people enough space to write. A small text field can feel uncomfortable to write in. When you know that Apple Pencil input is likely, improve the writing experience in your app by increasing the size of the text field before people begin to write in it or when they pause writing; avoid resizing a text field while people are writing. For developer guidance, see UIScribbleInteraction." + } + ] + }, + { + "heading": "Custom drawing", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Using PencilKit, you can let people take notes, annotate documents and images, and draw with the same low-latency experience that iOS provides. PencilKit also makes it easy to create a custom drawing canvas in your app and offer a state-of-the-art tool picker and ink palette." + }, + { + "type": "paragraph", + "text": "Help people draw on top of existing content. By default, the colors on your PencilKit canvas dynamically adjust to Dark Mode, so people can create content in either mode and the results will look great in both. However, when people draw on top of existing content like a PDF or a photo, you want to prevent the dynamic adjustment of colors so that the markup remains sharp and visible." + }, + { + "type": "paragraph", + "text": "Consider displaying custom undo and redo buttons when your app runs in a compact environment. In a regular environment, the tool picker includes undo and redo buttons, but in a compact environment it doesn’t. In a compact environment, you could display undo and redo buttons in a toolbar. You might also consider supporting the standard 3-finger undo/redo gesture, so people can use it in any environment. For guidance, see Undo and redo." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Entering data" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "PencilKit" + }, + { + "type": "paragraph", + "text": "PaperKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 7, 2024", + "Added guidance for handling squeeze and barrel roll on Apple Pencil Pro." + ], + [ + "September 12, 2023", + "Updated artwork." + ], + [ + "November 3, 2022", + "Added guidelines for using hover to enhance your app." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Best-practices" + }, + { + "title": "barrel roll", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Barrel-roll" + }, + { + "title": "Hover", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Hover" + }, + { + "title": "squeeze", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Squeeze" + }, + { + "title": "Double tap", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Double-tap" + }, + { + "title": "App Shortcut", + "url": "/design/human-interface-guidelines/app-shortcuts" + }, + { + "title": "Scribble", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Scribble" + }, + { + "title": "Custom drawing", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Custom-drawing" + }, + { + "title": "Undo and redo", + "url": "/design/human-interface-guidelines/undo-and-redo" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Related" + }, + { + "title": "Entering data", + "url": "/design/human-interface-guidelines/entering-data" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Camera Control", + "url": "https://developer.apple.com/design/human-interface-guidelines/camera-control", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On iPhone 16 and iPhone 16 Pro models, the Camera Control quickly opens your app’s camera experience to capture moments as they happen. When a person lightly presses the Camera Control, the system displays an overlay that extends from the device bezel." + }, + { + "type": "paragraph", + "text": "The overlay allows people to quickly adjust controls. A person can view the available controls by lightly double-pressing the Camera Control. After selecting a control, they can slide their finger on the Camera Control to adjust a value to capture their content as they want." + }, + { + "type": "paragraph", + "text": "Controls in the overlay" + } + ] + }, + { + "heading": "Anatomy", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Camera Control offers two types of controls for adjusting values or changing between options:" + }, + { + "type": "list", + "items": [ + "A slider provides a range of values to choose from, such as how much contrast to apply to the content.", + "A picker offers discrete options, such as turning a grid on and off in the viewfinder." + ] + }, + { + "type": "paragraph", + "text": "Slider control" + }, + { + "type": "paragraph", + "text": "Picker control" + }, + { + "type": "paragraph", + "text": "In addition to custom controls that you create, the system provides a set of standard controls that you can optionally include in the overlay to allow someone to adjust their camera’s zoom and exposure." + }, + { + "type": "paragraph", + "text": "Zoom factor control" + }, + { + "type": "paragraph", + "text": "Exposure bias control" + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use SF Symbols to represent control functionality. The system doesn’t support custom symbols; instead, pick a symbol from SF Symbols that clearly denotes a control’s behavior. iOS offers thousands of symbols you can use to represent the controls your app shows in the overlay. Symbols for controls don’t represent their current state. To view available symbols, see the Camera & Photos section in the SF Symbols app." + }, + { + "type": "paragraph", + "text": "The bolt.fill symbol that represents a control for the camera flash" + }, + { + "type": "paragraph", + "text": "The camera.filters symbol that represents a control for filters" + }, + { + "type": "paragraph", + "text": "Keep names of controls short. Control labels adhere to Dynamic Type sizes, and longer names may obfuscate the camera’s viewfinder." + }, + { + "type": "paragraph", + "text": "Include units or symbols with slider control values to provide context. Providing descriptive information in the overlay, such as EV, %, or a custom string, helps people understand what the slider controls. For developer guidance, see localizedValueFormat." + }, + { + "type": "paragraph", + "text": "Value with context" + }, + { + "type": "paragraph", + "text": "Value without context" + }, + { + "type": "paragraph", + "text": "Define prominent values for a slider control. Prominent values are ones people choose most frequently, or values that are evenly spaced, like the major increments of zoom factor. When a person slides on the Camera Control to adjust a slider control, the system more easily lands on prominent values you define. For developer guidance, see prominentValues." + }, + { + "type": "paragraph", + "text": "Make space for the overlay in the viewfinder. The overlay and control labels occupy the screen area adjacent to the Camera Control in both portrait and landscape orientations. To avoid overlapping the interface elements of your camera capture experience, place your UI outside of the overlay areas. Maximize the height and width of the viewfinder and allow the overlay to appear and disappear over it." + }, + { + "type": "paragraph", + "text": "Minimize distractions in the viewfinder. When capturing a photo or video, people appreciate a large preview image with as few visual distractions as possible. Avoid duplicating controls, like sliders and toggles, in your UI and the overlay when the system displays the overlay." + }, + { + "type": "paragraph", + "text": "Keep UI minimal." + }, + { + "type": "paragraph", + "text": "Avoid showing controls in the viewfinder that people access in the overlay." + }, + { + "type": "paragraph", + "text": "Enable or disable controls depending on the camera mode. For example, disable video controls when taking photos. The overlay supports multiple controls, but you can’t remove or add controls at runtime." + }, + { + "type": "paragraph", + "text": "Consider how to arrange your controls. Order commonly used controls toward the middle to allow quick access, and include lesser used controls on either side. When a person lightly presses the Camera Control to open the overlay again, the system remembers the last control they used in your app." + }, + { + "type": "paragraph", + "text": "Allow people to use the Camera Control to launch your experience from anywhere. Create a locked camera capture extension that lets people configure the Camera Control to launch your app’s camera experience from their locked device, the Home Screen, or from within other apps. For guidance, see Camera experiences on a locked device." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iPadOS, macOS, watchOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "SF Symbols" + }, + { + "type": "paragraph", + "text": "Controls" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Enhancing your app experience with the Camera Control — AVFoundation" + }, + { + "type": "paragraph", + "text": "AVCaptureControl — AVFoundation" + }, + { + "type": "paragraph", + "text": "LockedCameraCapture" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 9, 2024", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Anatomy", + "url": "/design/human-interface-guidelines/camera-control#Anatomy" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/camera-control#Best-practices" + }, + { + "title": "Camera experiences on a locked device", + "url": "/design/human-interface-guidelines/controls#Camera-experiences-on-a-locked-device" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/camera-control#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/camera-control#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/camera-control#Related" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Controls", + "url": "/design/human-interface-guidelines/controls" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/camera-control#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/camera-control#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Digital Crown", + "url": "https://developer.apple.com/design/human-interface-guidelines/digital-crown", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On both Apple Vision Pro and Apple Watch, people can use the Digital Crown to interact with the system; on Apple Watch, people can also use the Digital Crown to interact with apps." + }, + { + "type": "paragraph", + "text": "The Digital Crown on Apple Vision Pro" + }, + { + "type": "paragraph", + "text": "The Digital Crown on Apple Watch" + } + ] + }, + { + "heading": "Apple Vision Pro", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On Apple Vision Pro, people use the Digital Crown to:" + }, + { + "type": "list", + "items": [ + "Adjust volume", + "Adjust the amount of immersion in a portal, an Environment, or an app or game running in a Full Space (for guidance, see Immersive experiences)", + "Recenter content so it’s in front of them", + "Open Accessibility settings", + "Exit an app and return to the Home View" + ] + } + ] + }, + { + "heading": "Apple Watch", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As people turn the Digital Crown, it generates information you can use to enhance or facilitate interactions with your app, like scrolling or operating standard or custom controls." + }, + { + "type": "paragraph", + "text": "Starting with watchOS 10, the Digital Crown takes on an elevated role as the primary input for navigation. On the watch face, people turn the Digital Crown to view widgets in the Smart Stack, and on the Home Screen, people use it to move vertically through their collection of apps. Within apps, people turn the Digital Crown to switch between vertically paginated tabs, and to scroll through list views and variable height pages." + }, + { + "type": "paragraph", + "text": "Beyond its use for navigation, turning the Digital Crown generates information you can use to enhance or facilitate interactions with your app, such as inspecting data or operating standard or custom controls." + }, + { + "type": "note", + "text": "NoteApps don’t respond to presses on the Digital Crown because watchOS reserves these interactions for system-provided functionality like revealing the Home Screen." + }, + { + "type": "paragraph", + "text": "Most Apple Watch models provide haptic feedback for the Digital Crown, which gives people a more tactile experience as they scroll through content. By default, the system provides linear haptic detents — or taps — as people turn the Digital Crown a specific distance. Some system controls, like table views, provide detents as new items scroll onto the screen." + }, + { + "type": "paragraph", + "text": "Anchor your app’s navigation to the Digital Crown. Starting with watchOS 10, turning the Digital Crown is the main way people navigate within and between apps. List, tab, and scroll views are vertically oriented, allowing people to use the Digital Crown to easily move between the important elements of your app’s interface. When anchoring interactions to the Digital Crown, also be sure to back them up with corresponding touch screen interactions." + }, + { + "type": "paragraph", + "text": "Consider using the Digital Crown to inspect data in contexts where navigation isn’t necessary. In contexts where the Digital Crown doesn’t need to navigate through lists or between pages, it’s a great tool to inspect data in your app. For example, in World Clock, turning the Digital Crown advances the time of day at a selected location, allowing people to compare various times of day to their current time." + }, + { + "type": "paragraph", + "text": "Provide visual feedback in response to Digital Crown interactions. For example, pickers change the currently displayed value as people use the Digital Crown. If you track turns directly, use this data to update your interface programmatically. If you don’t provide visual feedback, people are likely to assume that turning the Digital Crown has no effect in your app." + }, + { + "type": "paragraph", + "text": "Update your interface to match the speed with which people turn the Digital Crown. People expect turning the Digital Crown to give them precise control over an interface, so it works well to use this speed to determine the speed at which you make changes. Avoid updating content at a rate that makes it difficult for people to select values." + }, + { + "type": "paragraph", + "text": "Use the default haptic feedback when it makes sense in your app. If haptic feedback doesn’t feel right in the context of your app — for example, if the default detents don’t match your app’s animation — turn off the detents. You can also adjust the haptic feedback behavior for tables, letting them use linear detents instead of row-based detents. For example, if your table has rows with significantly different heights, linear detents may give people a more consistent experience." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, macOS, or tvOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Action button" + }, + { + "type": "paragraph", + "text": "Immersive experiences" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "WKCrownDelegate — WatchKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Added artwork for Apple Vision Pro and Apple Watch, and clarified that visionOS apps don’t receive direct information from the Digital Crown." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "June 5, 2023", + "Added guidelines emphasizing the central role of the Digital Crown for navigation." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Apple Vision Pro", + "url": "/design/human-interface-guidelines/digital-crown#Apple-Vision-Pro" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Apple Watch", + "url": "/design/human-interface-guidelines/digital-crown#Apple-Watch" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/digital-crown#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/digital-crown#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/digital-crown#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Action button", + "url": "/design/human-interface-guidelines/action-button" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/digital-crown#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/digital-crown#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Eyes", + "url": "https://developer.apple.com/design/human-interface-guidelines/eyes", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When people look at an interactive element, visionOS highlights it, providing visual feedback that helps them confirm the item is one they want. The visual feedback, or hover effect, shows people that they can use an indirect gesture like tap to interact with the element." + }, + { + "type": "paragraph", + "text": "In some cases, the system can automatically display an expanded view of a component after people look at it. For example, when people look at a tab bar, the entire bar resizes to reveal text labels next to each tab. In this scenario, an individual tab also highlights before the tab bar expansion to let people select it before revealing the labels. Another example is a button that can reveal a tooltip when people look at it." + }, + { + "type": "important", + "text": "ImportantTo help preserve people’s privacy, visionOS doesn’t provide direct information about where people are looking before they tap. When you use system-provided components, visionOS automatically tells you when people tap the component. For developer guidance, see Adopting best practices for privacy and user preferences." + }, + { + "type": "paragraph", + "text": "visionOS also supports focus effects that help people navigate apps and the system using a connected input device like a keyboard or game controller. Focus effects are unrelated to the hover effect; to learn more, see Focus and selection." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Always give people multiple ways to interact with your app. Design your app to support the accessibility features people use to personalize the ways they interact with their devices. For guidance, see Accessibility." + }, + { + "type": "paragraph", + "text": "Design for visual comfort. Help people accomplish their primary task by making sure that the objects they need to use are within their field of view. When your app or game is running in the Shared Space or a Full Space, the system automatically places the first window or volume people open in a convenient location in front of them. While running in a Full Space, your app or game can also request access to information about a person’s head pose to help you place 3D content appropriately. In all cases, you can improve the visual comfort of your experience when you avoid requiring people to make multiple quick eye adjustments, either over a large area or through multiple levels of depth. For guidance, see Depth." + }, + { + "type": "paragraph", + "text": "Place content at a comfortable viewing distance. For example, to help people remain comfortable while they read or engage with content over time, aim to place it at least one meter away. In general, you don’t want to place content very close to people unless they’ll view or interact with it for only a little while." + }, + { + "type": "paragraph", + "text": "Prefer using standard UI components. System-provided components respond consistently when people look at them. If your custom components use different visual cues to provide visual feedback, it can be difficult for people to learn and remember how these components work." + } + ] + }, + { + "heading": "Making items easy to see", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Minimize visual distractions. When there’s a lot of visual noise, it can be difficult for people to find the object they’re looking for. Visual movement can be even more distracting: When people sense movement — especially in their peripheral vision — they tend to respond automatically by looking at it, making it hard to keep looking at the object they’re interested in. For example, revealing content near a button people are looking at can cause them to involuntarily look at the new content instead of the button." + }, + { + "type": "paragraph", + "text": "Make it easy for people to look at an item by providing enough space around it. Because eyes naturally tend to make small, quick adjustments in direction even while people are looking at one place, crowding UI objects together can make it difficult for people to look at one of them without jumping to another. You can help ensure that there’s enough space between interactive items by using a margin of at least 16 points around the bounds of each item or by placing items so that their centers are always at least 60 points apart. For additional layout guidance, see Layout and Spatial layout." + }, + { + "type": "paragraph", + "text": "Avoid using a repeating pattern or texture that fills the field of view. In some cases, people’s eyes can lock onto different elements in a pattern or texture, making the elements appear to have different depths. To avoid this effect, consider using the pattern in a smaller area." + } + ] + }, + { + "heading": "Encouraging interaction", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Consider using subtle visual cues to encourage people to look at the item they’re most likely to want. For example, it often works well to place the item near the center of the field of view or use techniques like gentle motion, increased contrast, or variations in color or scale to draw people’s attention. In general, prefer cues that are noticeable without being flashy or harsh." + }, + { + "type": "paragraph", + "text": "In general, give an interactive item a rounded shape. 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 an item’s shape, the easier it is for people to use their eyes to target it." + }, + { + "type": "paragraph", + "text": "If you create an interactive component that consists of more than one element, be sure to provide an overall containing shape that visionOS can highlight. For example, if an image and a label below it combine to act as one interactive component, you need to define a custom region that encompasses both elements, allowing visionOS to highlight the entire region when people look at either element." + } + ] + }, + { + "heading": "Custom hover effects", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When it makes sense in your app or game, you can design a hover effect that animates in a custom way when people look at an element, including system-provided or custom UI elements and RealityKit entities. You can use a custom hover effect to replace or augment a standard effect." + }, + { + "type": "paragraph", + "text": "Before you start designing custom hover effects, it’s important to understand how they work. To enable a custom hover effect for an element, you create two states or appearances for it: one that shows the custom hover effect and one that doesn’t. When someone looks at the element in your app or game, the system applies your predefined hover effect in a process that’s outside of your software’s process. This means that you don’t know when the system applies a custom hover effect or what state the element is in at that moment. The out-of-process nature of a custom hover effect also means that it can’t run code that requires knowing when people are looking at the element." + }, + { + "type": "paragraph", + "text": "As an example that shows what a custom hover effect can and can’t do, consider a photo-browsing app where a photo’s custom effect displays a different symbol depending on whether people have added the photo to Favorites. The app specifies the appropriate symbol for a photo’s custom hover effect and the system displays the effect if people look at the photo. However, the hover effect can’t perform the favoriting action because the system doesn’t tell the app when someone is looking at the photo." + }, + { + "type": "paragraph", + "text": "Prefer using a custom hover effect to emphasize or enhance a special moment in your experience. People are accustomed to the standard hover effects that provide visual feedback or, in the case of tab bars or tooltips, additional information, so a custom hover effect can be especially noticeable. Adding too many custom hover effects — or using them when standard effects are sufficient — can dilute the impact of your design, distract people from their task, and even cause visual discomfort." + }, + { + "type": "paragraph", + "text": "Choose the right delay. An element’s custom hover effect can appear instantly, after a short delay, or after a slightly longer delay, depending on how you expect people to interact with the element." + }, + { + "type": "list", + "items": [ + "No delay (default). A custom hover effect that appears without delay tends to be especially useful when the effect is subtle or invites interaction, like when a knob appears on a slider.", + "Short delay. Consider using a short delay to let people look at an element and quickly interact with it without waiting for the effect to appear; for example, the expansion of tabs in a tab bar works this way.", + "Long delay. If your custom hover effect shows additional information, like when a tooltip appears below a button, a slightly longer delay can work well because most people won’t need to view the additional information every time." + ] + }, + { + "type": "paragraph", + "text": "Aim to keep one or more of the element’s primary views unchanged in both states of a custom hover effect. When at least one primary view remains constant during a hover effect’s animation, it provides visual stability that can help people follow the element’s transition. If all of an element’s views move or change during a custom hover effect, it can disorient people and make them lose track of what’s happening." + }, + { + "type": "paragraph", + "text": "Thoroughly test custom hover effects. Testing is the only way to determine whether a custom hover effect looks good, responds appropriately, and makes your experience feel alive without distracting people. Aim to test your custom hover effects while wearing Apple Vision Pro so you can develop intuition about how to use them to enhance your experience." + } + ] + }, + { + "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": "Immersive experiences" + }, + { + "type": "paragraph", + "text": "Gestures" + }, + { + "type": "paragraph", + "text": "Spatial layout" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adopting best practices for privacy and user preferences — visionOS" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 10, 2024", + "Added guidance for custom hover effects." + ], + [ + "March 29, 2024", + "Added artwork showing the visionOS hover effect." + ], + [ + "October 24, 2023", + "Clarified the difference between focus effects and the visionOS hover effect." + ], + [ + "June 21, 2023", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "indirect gesture", + "url": "/design/human-interface-guidelines/gestures#visionOS" + }, + { + "title": "Focus and selection", + "url": "/design/human-interface-guidelines/focus-and-selection" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/eyes#Best-practices" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "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": "Making items easy to see", + "url": "/design/human-interface-guidelines/eyes#Making-items-easy-to-see" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "Spatial layout", + "url": "/design/human-interface-guidelines/spatial-layout" + }, + { + "title": "Encouraging interaction", + "url": "/design/human-interface-guidelines/eyes#Encouraging-interaction" + }, + { + "title": "Custom hover effects", + "url": "/design/human-interface-guidelines/eyes#Custom-hover-effects" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/eyes#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/eyes#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/eyes#Related" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/eyes#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/eyes#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/eyes#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Focus and selection", + "url": "https://developer.apple.com/design/human-interface-guidelines/focus-and-selection", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Focus supports simplified, component-based navigation. Using inputs like a remote, game controller, or keyboard, people bring focus to the components they want to interact with." + }, + { + "type": "paragraph", + "text": "In many cases, focusing an item also selects it. The exception is when automatic selection might cause a distracting context shift, like opening a new view. In tvOS, for example, people use the remote to move focus from item to item as they seek the one they want, but because selecting a focused item opens or activates it, selection requires a separate gesture." + }, + { + "type": "paragraph", + "text": "Different platforms communicate focus in different ways. For example, iPadOS and macOS show focus by drawing a ring around an item or highlighting it; tvOS generally uses the parallax effect to give the focused item an appearance of depth and liveliness. The combination of focus effects and interactions is sometimes called a focus system or focus model." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Rely on system-provided focus effects. System-defined focus effects are precisely tuned to complement interactions with Apple devices, providing experiences that feel responsive, fluid, and lifelike. Incorporating system-provided focus behaviors gives your app consistency and predictability, helping people understand it quickly. Consider creating custom focus effects only if it’s absolutely necessary." + }, + { + "type": "paragraph", + "text": "Avoid changing focus without people’s interaction. People rely on the focus system to help them know where they are in your app. If you change focus without their interaction, people have to spend time finding the newly focused item, delaying their current task. The exception is when people are moving focus using an input device that lets them make discrete, directional movements — like a keyboard, remote, or game controller — and a previously focused item disappears. In this scenario, there are only a small number of items within one discrete step of the previously focused item, so moving focus to one of these remaining items ensures that the focus indicator is in a location people can easily find. When people aren’t moving focus by using such an input device, you can’t predict the item they’ll target next, so it’s generally best to simply hide the focus indicator when the focused object disappears." + }, + { + "type": "paragraph", + "text": "Be consistent with the platform as you help people bring focus to items in your app. For example, in iPadOS and macOS, a full keyboard access mode helps people use the keyboard to reach every control, so you only need to support focus for content elements like list items, text fields, and search fields, and not for controls like buttons, sliders, and toggles. In contrast, tvOS users rely on using directional gestures on a remote or game controller (or pressing the arrow keys on an attached keyboard) to reach every onscreen element, so you need to make sure that people can bring focus to every element in your app." + }, + { + "type": "paragraph", + "text": "Indicate focus using visual appearances that are consistent with the platform. For example, consider a window that contains a list of items. In iPadOS and macOS, the system draws focused list items using white text and a background highlight that matches the app’s accent color, drawing unfocused items using the standard text color and a gray background highlight (for developer guidance, see UICollectionView and NSTableView)." + }, + { + "type": "paragraph", + "text": "In general, use a focus ring for a text or search field, but use a highlight in a list or collection. Although you can use a focus ring to draw attention to an item that fills a cell, like a photo, it’s usually easier for people to view lists and collections when an entire row is highlighted." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS or watchOS." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "iPadOS 15 and later defines a focus system that supports keyboard interactions for navigating text fields, text views, and sidebars, in addition to various types of collection views and other custom views in your app." + }, + { + "type": "paragraph", + "text": "The iPadOS and tvOS focus systems are similar. People perform actions by moving a focus indicator to an item and then selecting it (for guidance, see tvOS). Although the underlying system is the same, the user experiences are a little different. tvOS uses directional focus, which means people can use the same interaction — that is, swiping the Siri Remote or using only the arrow keys on a connected keyboard — to navigate to every onscreen component. In contrast, iPadOS defines focus groups, which represent specific areas within an app, like a sidebar, grid, or list. Using focus groups, iPadOS can support two different keyboard interactions." + }, + { + "type": "list", + "items": [ + "Pressing the Tab key moves focus among focus groups, letting people navigate to sidebars, grids, and other app areas.", + "Pressing an arrow key supports a directional focus interaction that’s similar to tvOS, but limited to navigation among items in the same focus group. For example, people can use an arrow key to move through the items in a list or a sidebar." + ] + }, + { + "type": "paragraph", + "text": "Onscreen components can indicate focus by using the halo effect or the highlighted appearance." + }, + { + "type": "paragraph", + "text": "The halo focus effect — also known as the focus ring — displays a customizable outline around the component. You can apply the halo effect to custom views and to fully opaque content within a collection or list cell, such as an image." + }, + { + "type": "paragraph", + "text": "Customize the halo focus effect when necessary. By default, the system uses an item’s shape to infer the shape of its halo. If the system-provided halo doesn’t give you the appearance you want, you can refine it to match contours like rounded corners or shapes defined by Bézier paths. You can also adjust a halo’s position if another component occludes or clips it. For example, you might need to ensure that a badge appears above the halo or that a parent view doesn’t clip it. For developer guidance, see UIFocusHaloEffect." + }, + { + "type": "paragraph", + "text": "The highlighted appearance — in which the component’s text uses the app’s accent color — also indicates focus, but it’s not a focus effect. The highlight appearance occurs automatically when people select a collection view cell on which you’ve set content configurations (for developer guidance, see UICollectionViewCell)." + }, + { + "type": "paragraph", + "text": "Ensure that focus moves through your custom views in ways that make sense. As people continue pressing the Tab key, focus moves through focus groups in reading order: leading to trailing, and top to bottom. Although focus moves through system-provided views in ways that people expect, you might need to adjust the order in which the focus system visits your custom views. For example, if you want focus to move down through a vertical stack of custom views before it moves in the trailing direction to the next view, you need to identify the stack container as a single focus group. For developer guidance, see focusGroupIdentifier." + }, + { + "type": "paragraph", + "text": "Adjust the priority of an item to reflect its importance within a focus group. When a group receives focus, its primary item automatically receives focus too, making it easy for people to select the item they’re most likely to want. You can make an item primary by increasing its priority. For developer guidance, see UIFocusGroupPriority." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In a full-screen experience, let people use gestures to interact with the content, not to move focus. When an item displays in full screen, it doesn’t show focus, so people naturally assume that their gestures will affect the object, and not its focus state." + }, + { + "type": "paragraph", + "text": "Avoid displaying a pointer. People expect to navigate a fixed number of items by changing focus, not by trying to drag a tiny pointer around a huge screen. While free-form movement might make sense during gameplay, such as when looking for a hidden object or flying a plane, use the focus model when people navigate menus and other interface elements. If your app requires a pointer, make sure it’s highly visible and feels integrated with your experience." + }, + { + "type": "paragraph", + "text": "Design your interface to accommodate components in various focus states. In tvOS, focusable items can have up to five different states, each of which is visually distinct. Because focusing an item often increases its scale, you need to supply assets for the larger, focused size to ensure they always look sharp, and you need to make sure the larger item doesn’t crowd the surrounding interface." + }, + { + "type": "table", + "rows": [ + [ + "State", + "Description" + ], + [ + "", + "The viewer hasn’t brought focus to the item. Unfocused items appear less prominent than focused items." + ], + [ + "", + "The viewer brings focus to the item. A focused item visually stands out from the other onscreen content through elevation to the foreground, illumination, and animation." + ], + [ + "", + "The viewer chooses the focused item. A focused item provides instant visual feedback when people choose it. For example, a button might briefly invert its colors and animate before it transitions to its selected appearance." + ], + [ + "", + "The viewer has chosen or activated the item in some way. For example, a heart-shaped button that people can use to favorite a photo might appear filled in the selected state and empty in the deselected state." + ], + [ + "", + "The viewer can’t bring focus to the item or choose it. An unavailable item appears inactive." + ] + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see Adding user-focusable elements to a tvOS app." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "visionOS supports the same focus system as in iPadOS and tvOS, letting people use a connected input device like a keyboard or game controller to interact with apps and the system." + }, + { + "type": "note", + "text": "NoteWhen people look at a virtual object to identify it as the object they want to interact with, the system uses the hover effect, not a focus effect, to provide visual feedback (for guidance, see Eyes). The hover effect isn’t related to the focus system." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Eyes" + }, + { + "type": "paragraph", + "text": "Keyboards" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Focus Attributes — TVML" + }, + { + "type": "paragraph", + "text": "Focus-based navigation — UIKit" + }, + { + "type": "paragraph", + "text": "About focus interactions for Apple TV — UIKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "October 24, 2023", + "Clarified the difference between focus effects and the visionOS hover effect." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "parallax effect", + "url": "/design/human-interface-guidelines/images#Parallax-effect" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/focus-and-selection#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/focus-and-selection#Platform-considerations" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/focus-and-selection#iPadOS" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/focus-and-selection#tvOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/focus-and-selection#visionOS" + }, + { + "title": "Eyes", + "url": "/design/human-interface-guidelines/eyes" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/focus-and-selection#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/focus-and-selection#Related" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/focus-and-selection#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/focus-and-selection#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/focus-and-selection#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Game controls", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-controls", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On Apple platforms, a game can support input from physical game controllers or default system interactions, like touch, a remote, or a mouse and keyboard. Players might prefer to use physical game controllers, but there are two important reasons to also support a platform’s default interaction methods:" + }, + { + "type": "list", + "items": [ + "Even though all platforms except watchOS support physical game controllers, not every player might have access to one.", + "Players appreciate games that let them use the platform interaction method they’re most familiar with." + ] + }, + { + "type": "paragraph", + "text": "To reach the widest audience and provide the best experience for each platform, keep these factors in mind when choosing the input methods to support." + } + ] + }, + { + "heading": "Touch controls", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "For iOS and iPadOS games, supporting touch interaction means that you can provide virtual controls on top of game content while also letting players interact with game elements by touching them directly. You can use the Touch Controller framework to add these virtual controls to your game. Keep the following guidelines in mind to create an enjoyable touch control experience." + }, + { + "type": "paragraph", + "text": "Determine whether it makes sense to display virtual controls on top of game content. In general, virtual game controls benefit games that offer a large number of actions or require players to control movement. However, sometimes gameplay is more immersive and effective when players can interact directly with in-game objects. Look for opportunities to reduce the amount of virtual controls that overlap your game content by associating actions with in-game gestures instead. For example, consider letting players tap objects to select them instead of adding a virtual selection button." + }, + { + "type": "paragraph", + "text": "Place virtual buttons where they’re easy to access. Take into account the device’s boundaries and safe areas as well as comfortable locations for controls. Make sure to position buttons where they don’t overlap system features like the Home indicator or Dynamic Island on iPhone. Place frequently used buttons near a player’s thumb, avoiding the circular regions where players expect movement and camera input to happen. Place secondary controls, like menus, at the top of the screen." + }, + { + "type": "paragraph", + "text": "Placing virtual controls within reach of people’s thumbs can make your game more comfortable to play." + }, + { + "type": "paragraph", + "text": "Make sure controls are large enough. Make sure frequently used controls are a minimum size of 44x44 pt, and less important controls, such as menus, are a minimum size of 28x28 pt to accommodate people’s fingers." + }, + { + "type": "paragraph", + "text": "Always include visible and tactile press states. A virtual control feels unresponsive without a visual and physical press state. Help players understand when they successfully interact with a button by adding a visual press state effect, such as a glow, that they can see even when their finger is covering the control. Combine this press state with sound and haptics to enhance the feeling of feedback. For guidance, see Playing haptics." + }, + { + "type": "paragraph", + "text": "Use symbols that communicate the actions they perform. Choose artwork that visually represents the action each button performs, such as a graphic of a weapon to represent an attack. Avoid using abstract shapes or controller-based naming like A, X, or R1 as artwork, which makes it harder for players to understand and remember what specific controls do." + }, + { + "type": "paragraph", + "text": "Show and hide virtual controls to reflect gameplay. Take advantage of the dynamic nature of touch controls and adapt what controls players see onscreen depending on their context. You can hide controls when an action isn’t available or relevant, letting you reduce clutter and help players concentrate on what’s important. For example, consider hiding movement controls until a player touches the screen to reduce the amount of UI overlapping your game content." + }, + { + "type": "paragraph", + "text": "When the thumbstick moves to the right, it becomes more visible and shows a highlight to indicate the movement direction." + }, + { + "type": "paragraph", + "text": "When the thumbstick is at rest, the virtual control fades to show it’s not in use." + }, + { + "type": "paragraph", + "text": "Combine functionality into a single control. Consider redesigning game mechanics that require players to press multiple buttons at the same time or in a sequence. Leverage gestures such as double tap and touch and hold to provide different variations of the same action, such as touch and hold to use a special powered up version of an attack. For multiple actions, such as walking or sprinting, consider combining the actions into a single control." + }, + { + "type": "paragraph", + "text": "Map movement and camera controls to predictable behavior. Typically, players expect to control movement using the left side of their screen, and control camera direction using the right side of their screen. Maximize the amount of space that players can control both movement and the camera direction by using as large of an input area as possible. For movement control, opt to show a virtual thumbstick wherever the player lands their thumb instead of a static thumbstick position. For camera control, opt to use direct touch to pan the camera instead of a virtual thumbstick." + } + ] + }, + { + "heading": "Physical controllers", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support the platform’s default interaction method. A game controller is an optional purchase, but every iPhone and iPad has a touchscreen, every Mac has a keyboard and a trackpad or mouse, every Apple TV has a remote, and every Apple Vision Pro responds to gestures people make with their eyes and hands. If you support game controllers, try to make sure there’s a fallback for using the platform’s default interaction method. For developer guidance, see Adding virtual controls to games that support game controllers in iOS." + }, + { + "type": "paragraph", + "text": "Tell people about game controller requirements. In tvOS and visionOS, you can require the use of a physical game controller. The App Store displays a “Game Controller Required” badge to help people identify such apps. Remember that people can open your game at any time, even without a connected controller. If your app requires a game controller, check for its presence and gracefully prompt people to connect one. For developer guidance, see GCRequiresControllerUserInteraction." + }, + { + "type": "paragraph", + "text": "Automatically detect whether a controller is paired. Instead of having players manually set up a physical game controller, you can automatically detect whether a controller is paired and get its profile. For developer documentation, see Game Controller." + }, + { + "type": "paragraph", + "text": "Customize onscreen content to match the connected game controller. To simplify your game’s code, the Game Controller framework assigns standard names to controller elements based on their placement, but the colors and symbols on an actual game controller may differ. Be sure to use the connected controller’s labeling scheme when referring to controls or displaying related content in your interface. For developer guidance, see GCControllerElement." + }, + { + "type": "paragraph", + "text": "Map controller buttons to expected UI behavior. Outside of gameplay, players expect to navigate your game’s UI in a way that matches the familiar behavior of the platform they’re playing on. When not controlling gameplay, follow these conventions across all Apple platforms:" + }, + { + "type": "table", + "rows": [ + [ + "Button", + "Expected behavior for UI" + ], + [ + "A", + "Activates a control" + ], + [ + "B", + "Cancels an action or returns to previous screen" + ], + [ + "X", + "—" + ], + [ + "Y", + "—" + ], + [ + "Left shoulder", + "Navigates left to a different screen or section" + ], + [ + "Right shoulder", + "Navigates right to a different screen or section" + ], + [ + "Left trigger", + "—" + ], + [ + "Right trigger", + "—" + ], + [ + "Left/right thumbstick", + "Moves selection" + ], + [ + "Directional pad", + "Moves selection" + ], + [ + "Home/logo", + "Reserved for system controls" + ], + [ + "Menu", + "Opens game settings or pauses gameplay" + ] + ] + }, + { + "type": "paragraph", + "text": "Support multiple connected controllers. If there are multiple controllers connected, use labels and glyphs that match the one that the player is actively using. If your game supports multiplayer, use the appropriate labels and symbols when referring to a specific player’s controller. If you need to refer to buttons on multiple controllers, consider listing them together." + }, + { + "type": "paragraph", + "text": "Prefer using symbols, not text, to refer to game controller elements. The Game Controller framework makes SF Symbols available for most elements, including the buttons on various brands of game controllers. Using symbols instead of text descriptions can be especially helpful for players who aren’t experienced with controllers because it doesn’t require them to hunt for a specific button label during gameplay." + } + ] + }, + { + "heading": "Keyboards", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Keyboard players appreciate using keyboard bindings to speed up their interactions with apps and games." + }, + { + "type": "paragraph", + "text": "Prioritize single-key commands. Single-key commands are generally easier and faster for players to perform, especially while they’re simultaneously using a mouse or trackpad. For example, you might use the first letter of a menu item as a shortcut, such as I for Inventory or M for Map; you might also map the game’s main action to the Space bar, taking advantage of the key’s relatively large size." + }, + { + "type": "paragraph", + "text": "Test key binding comfort game using an Apple keyboard. For example, if a key binding uses the Control key (^) on a non-Apple keyboard, consider remapping it to the Command key (⌘) on an Apple keyboard. On Apple keyboards, the Command key is conveniently located next to the Space bar, making it especially easy to reach when players are using the W, A, S, and D keys." + }, + { + "type": "paragraph", + "text": "Take the proximity of keys into account. For example, if players navigate using the W, A, S, and D keys, consider using nearby keys to define other high-value commands. Similarly, if there’s a group of closely related actions, it can work well to map their bindings to keys that are physically close together, such as using the number keys for inventory categories." + }, + { + "type": "paragraph", + "text": "Let players customize key bindings. Although players tend to expect a reasonable set of defaults, many people need to customize a game’s key bindings for personal comfort and play style." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Match spatial game controller behavior to hand input. In addition to supporting a wide array of wireless game controllers, your visionOS game can also support spatial game controllers such as PlayStation VR2 Sense controller. Allow players to interact with your game in a similar manner to how they interact using their hands. Specifically, support looking at an object and pressing the controller’s left or right trigger button to indirectly interact, or reaching out and pressing the left or right trigger button to directly interact. For more information, see visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Designing for games" + }, + { + "type": "paragraph", + "text": "Gestures" + }, + { + "type": "paragraph", + "text": "Keyboards" + }, + { + "type": "paragraph", + "text": "Playing haptics" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Create games for Apple platforms" + }, + { + "type": "paragraph", + "text": "Touch Controller" + }, + { + "type": "paragraph", + "text": "Game Controller" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated touch control best practices, updated game controller mapping for UI, and added guidance for spatial game controller support in visionOS." + ], + [ + "June 10, 2024", + "Added guidance for supporting touch controls and changed title from Game controllers." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Touch controls", + "url": "/design/human-interface-guidelines/game-controls#Touch-controls" + }, + { + "title": "safe areas", + "url": "/design/human-interface-guidelines/layout#Guides-and-safe-areas" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Physical controllers", + "url": "/design/human-interface-guidelines/game-controls#Physical-controllers" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/game-controls#Keyboards" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/game-controls#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/game-controls#visionOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/gestures#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/game-controls#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/game-controls#Related" + }, + { + "title": "Designing for games", + "url": "/design/human-interface-guidelines/designing-for-games" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/game-controls#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/game-controls#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/game-controls#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Gestures", + "url": "https://developer.apple.com/design/human-interface-guidelines/gestures", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Depending on the device they’re using, people can make gestures on a touchscreen, in the air, or on a range of input devices such as a trackpad, mouse, remote, or game controller that includes a touch surface." + }, + { + "type": "paragraph", + "text": "Every platform supports basic gestures like tap, swipe, and drag. Although the precise movements that make up basic gestures can vary per platform and input device, people are familiar with the underlying functionality of these gestures and expect to use them everywhere. For a list of these gestures, see Standard gestures." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Give people more than one way to interact with your app. People commonly prefer or need to use other inputs — such as their voice, keyboard, or Switch Control — to interact with their devices. Don’t assume that people can use a specific gesture to perform a given task. For guidance, see Accessibility." + }, + { + "type": "paragraph", + "text": "In general, respond to gestures in ways that are consistent with people’s expectations. People expect most gestures to work the same regardless of their current context. For example, people expect tap to activate or select an object. Avoid using a familiar gesture like tap or swipe to perform an action that’s unique to your app; similarly, avoid creating a unique gesture to perform a standard action like activating a button or scrolling a long view." + }, + { + "type": "paragraph", + "text": "Handle gestures as responsively as possible. Useful gestures enhance the experience of direct manipulation and provide immediate feedback. As people perform a gesture in your app, provide feedback that helps them predict its results and, if necessary, communicates the extent and type of movement required to complete the action." + }, + { + "type": "paragraph", + "text": "Indicate when a gesture isn’t available. If you don’t clearly communicate why a gesture doesn’t work, people might think your app has frozen or they aren’t performing the gesture correctly, leading to frustration. For example, if someone tries to drag a locked object, the UI may not indicate that the object’s position has been locked; or if they try to activate an unavailable button, the button’s unavailable state may not be clearly distinct from its available state." + } + ] + }, + { + "heading": "Custom gestures", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Add custom gestures only when necessary. Custom gestures work best when you design them for specialized tasks that people perform frequently and that aren’t covered by existing gestures, like in a game or drawing app. If you decide to implement a custom gesture, make sure it’s:" + }, + { + "type": "list", + "items": [ + "Discoverable", + "Straightforward to perform", + "Distinct from other gestures", + "Not the only way to perform an important action in your app or game" + ] + }, + { + "type": "paragraph", + "text": "Make custom gestures easy to learn. Offer moments in your app to help people quickly learn and perform custom gestures, and make sure to test your interactions in real use scenarios. If you’re finding it difficult to use simple language and graphics to describe a gesture, it may mean people will find the gesture difficult to learn and perform." + }, + { + "type": "paragraph", + "text": "Use shortcut gestures to supplement standard gestures, not replace them. While you may supply a custom gesture to quickly access parts of your app, people also need simple, familiar ways to navigate and perform actions, even if it means an extra tap or two. For example, in an app that supports navigation through a hierarchy of views, people expect to find a Back button in a top toolbar that lets them return to the previous view with a single tap. To help accelerate this action, many apps also offer a shortcut gesture — such as swiping from the side of a window or touchscreen — while continuing to provide the Back button." + }, + { + "type": "paragraph", + "text": "Avoid conflicting with gestures that access system UI. Several platforms offer gestures for accessing system behaviors, like edge swiping in watchOS or rolling your hand over to access system overlays in visionOS. It’s important to avoid defining custom gestures that might conflict with these interactions, as people expect these controls to work consistently. In specific circumstances within games or immersive experiences, developers can work around this area by deferring the system gesture. For more information, see the platform considerations for iOS, iPadOS, watchOS, and visionOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In addition to the standard gestures supported in all platforms, iOS and iPadOS support a few other gestures that people expect." + }, + { + "type": "table", + "rows": [ + [ + "Gesture", + "Common action" + ], + [ + "Three-finger swipe", + "Initiate undo (left swipe); initiate redo (right swipe)." + ], + [ + "Three-finger pinch", + "Copy selected text (pinch in); paste copied text (pinch out)." + ], + [ + "Four-finger swipe (iPadOS only)", + "Switch between apps." + ], + [ + "Shake", + "Initiate undo; initiate redo." + ] + ] + }, + { + "type": "paragraph", + "text": "Consider allowing simultaneous recognition of multiple gestures if it enhances the experience. Although simultaneous gestures are unlikely to be useful in nongame apps, a game might include multiple onscreen controls — such as a joystick and firing buttons — that people can operate at the same time. For guidance on integrating touchscreen input with Apple Pencil input in your iPadOS app, see Apple Pencil and Scribble." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People primarily interact with macOS using a keyboard and mouse. In addition, they can make standard gestures on a Magic Trackpad, Magic Mouse, or a game controller that includes a touch surface." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People expect to use standard gestures to navigate tvOS apps and games with a compatible remote, Siri Remote, or game controller that includes a touch surface. For guidance, see Remotes." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "visionOS supports two categories of gestures: indirect and direct." + }, + { + "type": "paragraph", + "text": "People use an indirect gesture by looking at an object to target it, and then manipulating that object from a distance — indirectly — with their hands. For example, a person can look at a button to focus it and select it by quickly tapping their finger and thumb together. Indirect gestures are comfortable to perform at any distance, and let people quickly change focus between different objects and select items with minimal movement." + }, + { + "type": "paragraph", + "text": "People use a direct gesture to physically touch an interactive object. For example, people can directly type on the visionOS keyboard by tapping the virtual keys. Direct gestures work best when they are within reach. Because people may find it tiring to keep their arms raised for extended periods, direct gestures are best for infrequent use. visionOS also supports direct versions of all standard gestures, allowing people the choice to interact directly or indirectly with any standard component." + }, + { + "type": "paragraph", + "text": "Here are the standard direct gestures people use in visionOS; see Specifications for a list of standard indirect gestures." + }, + { + "type": "table", + "rows": [ + [ + "Direct gesture", + "Common use" + ], + [ + "Touch", + "Directly select or activate an object." + ], + [ + "Touch and hold", + "Open a contextual menu." + ], + [ + "Touch and drag", + "Move an object to a new location." + ], + [ + "Double touch", + "Preview an object or file; select a word in an editing context." + ], + [ + "Swipe", + "Reveal actions and controls; dismiss views; scroll." + ], + [ + "With two hands, pinch and drag together or apart", + "Zoom in or out." + ], + [ + "With two hands, pinch and drag in a circular motion", + "Rotate an object." + ] + ] + }, + { + "type": "paragraph", + "text": "Support standard gestures everywhere you can. For example, as soon as someone looks at an object in your app or game, tap is the first gesture they’re likely to make when they want to select or activate it. Even if you also support custom gestures, supporting standard gestures such as tap helps people get comfortable with your app or game quickly." + }, + { + "type": "paragraph", + "text": "Offer both indirect and direct interactions when possible. Prefer indirect gestures for UI and common components like buttons. Reserve direct gestures and custom gestures for objects that invite close-up interaction or specific motions in a game or interactive experience." + }, + { + "type": "paragraph", + "text": "Avoid requiring specific body movements or positions for input. Not all people can perform specific body movements or position themselves in certain ways at all times, whether due to disability, spatial constraints, or other environmental factors. If your experience requires movement, consider supporting alternative inputs to let people choose the interaction method that works best for them." + } + ] + }, + { + "heading": "Designing custom gestures in visionOS", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "If you want to offer a specific interaction for your experience that people can’t perform using an existing system gesture, consider designing a custom gesture. To offer this type of interaction, your app needs to be running in a Full Space, and you must request people’s permission to access information about their hands. For developer guidance, see Setting up access to ARKit data." + }, + { + "type": "paragraph", + "text": "Prioritize comfort. Continually test ergonomics of all interactions that require custom gestures. A custom interaction that requires people to keep their arms raised for even a little while can be physically tiring, and repeating very similar movements many times in succession can stress people’s muscles and joints." + }, + { + "type": "paragraph", + "text": "Carefully consider complex custom gestures that involve multiple fingers or both hands. People may not always have both hands available when using your app or game. If you require a more complex gesture for your experience, consider also offering an alternative that requires less movement." + }, + { + "type": "paragraph", + "text": "Avoid custom gestures that require using a specific hand. It can increase someone’s cognitive load if they need to remember which hand to use to trigger a custom gesture. It may also make your experience less welcoming to people with strong hand-dominance or limb differences." + } + ] + }, + { + "heading": "Working with system overlays in visionOS", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "In visionOS 2 and later, people can look at the palm of one hand and use gestures to quickly access system overlays for Home and Control Center. These interactions are available systemwide, and are reserved solely for accessing system overlays." + }, + { + "type": "note", + "text": "NoteThe system overlay is the default method of accessing Control Center in visionOS 2 and later. The visionOS 1 behavior (looking upward) remains available as an accessibility setting." + }, + { + "type": "paragraph", + "text": "When designing apps and games that use custom gestures or anchor content to a person’s hands, it’s important to take interactions with the system overlays into consideration." + }, + { + "type": "paragraph", + "text": "Reserve the area around a person’s hand for system overlays and their related gestures. If possible, don’t anchor content to a person’s hands or wrists. If you’re designing a game that involves hand-anchored content, place it outside of the immediate area of someone’s hand to avoid colliding with the Home indicator." + }, + { + "type": "paragraph", + "text": "The area reserved for interacting with system overlays." + }, + { + "type": "paragraph", + "text": "A person looks at their palm to reveal the Home indicator." + }, + { + "type": "paragraph", + "text": "A person turns their hand to reveal the status bar, and can tap to open Control Center." + }, + { + "type": "paragraph", + "text": "Consider deferring the system overlay behavior when designing an immersive app or game. In certain circumstances, you may not want the Home indicator to appear when someone looks at the palm of their hand. For example, a game that uses virtual hands or gloves may want to keep someone within the world of the story, even if they happen to look at their hands from different angles. In such cases, when your app is running in a Full Space, you can choose to require a tap to reveal the Home indicator instead. For developer guidance, see persistentSystemOverlays(_:)." + }, + { + "type": "paragraph", + "text": "Default behavior in the Shared Space" + }, + { + "type": "paragraph", + "text": "Default behavior in a Full Space" + }, + { + "type": "paragraph", + "text": "Deferred behavior in a Full Space" + }, + { + "type": "note", + "text": "NoteApps and games that you built for visionOS 1 defer the system overlay behavior by default. When a person looks at their palm with your app running in a Full Space, the Home indicator won’t appear unless they tap first." + }, + { + "type": "paragraph", + "text": "Use caution when designing custom gestures that involve a rolling motion of the hand, wrist, and forearm. This specific motion is reserved for revealing system overlays. Since system overlays always display on top of app content and your app isn’t aware of when they’re visible, it’s important to test any custom gestures or content that might conflict." + } + ] + }, + { + "heading": "Double tap", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "In watchOS 11 and later, people can use the double-tap gesture to scroll through lists and scroll views, and to advance between vertical tab views. Additionally, you can specify a toggle or button as the primary action in your app, or in your widget or Live Activity when the system displays it in the Smart Stack. Double-tapping in a view with a primary action highlights the control and then performs the action. The system also supports double tap for custom actions that you offer in notifications, where it acts on the first nondestructive action in the notification." + }, + { + "type": "paragraph", + "text": "Avoid setting a primary action in views with lists, scroll views, or vertical tabs. This conflicts with the default navigation behaviors that people expect when they double-tap." + }, + { + "type": "paragraph", + "text": "Choose the button that people use most commonly as the primary action in a view. Double tap is helpful in a nonscrolling view when it performs the action that people use the most. For example, in a media controls view, you could assign the primary action to the play/pause button. For developer guidance, see handGestureShortcut(_:isEnabled:) and primaryAction." + } + ] + }, + { + "heading": "Standard gestures", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The system provides APIs that support the familiar gestures people use with their devices, whether they use a touchscreen, an indirect gesture in visionOS, or an input device like a trackpad, mouse, remote, or game controller. For developer guidance, see Gestures." + }, + { + "type": "table", + "rows": [ + [ + "Gesture", + "Supported in", + "Common action" + ], + [ + "Tap", + "iOS, iPadOS, macOS, tvOS, visionOS, watchOS", + "Activate a control; select an item." + ], + [ + "Swipe", + "iOS, iPadOS, macOS, tvOS, visionOS, watchOS", + "Reveal actions and controls; dismiss views; scroll." + ], + [ + "Drag", + "iOS, iPadOS, macOS, tvOS, visionOS, watchOS", + "Move a UI element." + ], + [ + "Touch (or pinch) and hold", + "iOS, iPadOS, tvOS, visionOS, watchOS", + "Reveal additional controls or functionality." + ], + [ + "Double tap", + "iOS, iPadOS, macOS, tvOS, visionOS, watchOS", + "Zoom in; zoom out if already zoomed in; perform a primary action on Apple Watch Series 9 and Apple Watch Ultra 2." + ], + [ + "Zoom", + "iOS, iPadOS, macOS, tvOS, visionOS", + "Zoom a view; magnify content." + ], + [ + "Rotate", + "iOS, iPadOS, macOS, tvOS, visionOS", + "Rotate a selected item." + ] + ] + }, + { + "type": "paragraph", + "text": "For guidance on supporting additional gestures and button presses on specific input devices, see Pointing devices, Remotes, and Game controls." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Eyes" + }, + { + "type": "paragraph", + "text": "Playing haptics" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Gestures — SwiftUI" + }, + { + "type": "paragraph", + "text": "UITouch — UIKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 9, 2024", + "Added guidance for working with system overlays in visionOS and made organizational updates." + ], + [ + "September 15, 2023", + "Updated specifications to include double tap in watchOS." + ], + [ + "June 21, 2023", + "Changed page title from Touchscreen gestures and updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Standard gestures", + "url": "/design/human-interface-guidelines/gestures#Standard-gestures" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/gestures#Best-practices" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Custom gestures", + "url": "/design/human-interface-guidelines/gestures#Custom-gestures" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/gestures#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/gestures#iOS-iPadOS" + }, + { + "title": "Apple Pencil and Scribble", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/gestures#macOS" + }, + { + "title": "keyboard", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "game controller", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/gestures#tvOS" + }, + { + "title": "Remotes", + "url": "/design/human-interface-guidelines/remotes" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/gestures#visionOS" + }, + { + "title": "Specifications", + "url": "/design/human-interface-guidelines/gestures#Specifications" + }, + { + "title": "Designing custom gestures in visionOS", + "url": "/design/human-interface-guidelines/gestures#Designing-custom-gestures-in-visionOS" + }, + { + "title": "Working with system overlays in visionOS", + "url": "/design/human-interface-guidelines/gestures#Working-with-system-overlays-in-visionOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/gestures#watchOS" + }, + { + "title": "Double tap", + "url": "/design/human-interface-guidelines/gestures#Double-tap" + }, + { + "title": "notifications", + "url": "/design/human-interface-guidelines/notifications" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/gestures#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/gestures#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Eyes", + "url": "/design/human-interface-guidelines/eyes" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/gestures#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/gestures#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/gestures#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Gyroscope and accelerometer", + "url": "https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can use accelerometer and gyroscope data to provide experiences based on real-time, motion-based information in apps and games that run in iOS, iPadOS, and watchOS. tvOS apps can use gyroscope data from the Siri Remote. For developer guidance, see Core Motion." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use motion data only to offer a tangible benefit to people. For example, a fitness app might use the data to provide feedback about people’s activity and general health, and a game might use the data to enhance gameplay. Avoid gathering data simply to have the data." + }, + { + "type": "important", + "text": "ImportantIf your experience needs to access motion data from a device, you must provide copy that explains why. The first time your app or game tries to access this type of data, the system includes your copy in a permission request, where people can grant or deny access." + }, + { + "type": "paragraph", + "text": "Outside of active gameplay, avoid using accelerometers or gyroscopes for the direct manipulation of your interface. Some motion-based gestures may be difficult to replicate precisely, may be physically challenging for some people to perform, and may affect battery usage." + } + ] + }, + { + "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": "Feedback" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Getting processed device-motion data — Core Motion" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Inputs", + "url": "https://developer.apple.com/design/human-interface-guidelines/inputs", + "category": "inputs", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Action button", + "url": "/design/human-interface-guidelines/action-button" + }, + { + "title": "Apple Pencil and Scribble", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble" + }, + { + "title": "Camera Control", + "url": "/design/human-interface-guidelines/camera-control" + }, + { + "title": "Digital Crown", + "url": "/design/human-interface-guidelines/digital-crown" + }, + { + "title": "Eyes", + "url": "/design/human-interface-guidelines/eyes" + }, + { + "title": "Focus and selection", + "url": "/design/human-interface-guidelines/focus-and-selection" + }, + { + "title": "Game controls", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Gyroscope and accelerometer", + "url": "/design/human-interface-guidelines/gyro-and-accelerometer" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Nearby interactions", + "url": "/design/human-interface-guidelines/nearby-interactions" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Remotes", + "url": "/design/human-interface-guidelines/remotes" + } + ], + "image_count": 0 + }, + { + "title": "Keyboards", + "url": "https://developer.apple.com/design/human-interface-guidelines/keyboards", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People can connect a physical keyboard to any device except Apple Watch. Mac users tend to use a physical keyboard all the time and iPad users often do. Many games work well with a physical keyboard, and people can prefer using one instead of a virtual keyboard when entering a lot of text." + }, + { + "type": "paragraph", + "text": "Keyboard users often appreciate using keyboard shortcuts to speed up their interactions with apps and games. A keyboard shortcut is a combination of a primary key and one or more modifier keys (Control, Option, Shift, and Command) that map to a specific command. A keyboard shortcut in a game — called a key binding — often consists of a single key." + }, + { + "type": "paragraph", + "text": "Apple defines standard keyboard shortcuts to work consistently across the system and most apps, helping people transfer their knowledge to new experiences. Some apps define custom keyboard shortcuts for the app-specific commands people use most; most games define custom key bindings that make it quick and efficient to use the keyboard to control the game. For guidance, see Game controls." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support Full Keyboard Access when possible. Available in iOS, iPadOS, macOS, and visionOS, Full Keyboard Access lets people navigate and activate windows, menus, controls, and system features using only the keyboard. To test Full Keyboard Access in your app or game, turn it on in the Accessibility area of the system-supplied Settings app. For developer guidance, see Support Full Keyboard Access in your iOS app and isFullKeyboardAccessEnabled." + }, + { + "type": "important", + "text": "ImportantAlthough iPadOS supports keyboard navigation in text fields, text views, and sidebars, and provides APIs you can use to support it in collection views and other custom views, avoid supporting keyboard navigation for controls, such as buttons, segmented controls, and switches. Instead, let people use Full Keyboard Access to activate controls, navigate to all onscreen components, and perform gesture-based interactions like drag and drop. For guidance, see iPadOS; for developer guidance, see Focus-based navigation." + }, + { + "type": "paragraph", + "text": "Respect standard keyboard shortcuts. While using most apps, people generally expect to rely on the standard keyboard shortcuts that work in other apps and throughout the system. If your app offers a unique action that people perform frequently, prefer creating a custom shortcut for it instead of repurposing a standard one that people associate with a different action. While playing a game, people may expect to use certain standard keyboard shortcuts — such as Command–Q to quit the game — but they also expect to be able to modify each game’s key bindings to fit their personal play style. For guidance, see Game controls." + } + ] + }, + { + "heading": "Standard keyboard shortcuts", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In general, don’t repurpose standard keyboard shortcuts for custom actions. People can get confused when the shortcuts they know work differently in your app or game. Only consider redefining a standard shortcut if its action doesn’t make sense in your experience. For example, if your app doesn’t support text editing, it doesn’t need a text-styling command like Italic, so you might repurpose Command–I for an action that has more relevance, like Get Info." + }, + { + "type": "paragraph", + "text": "People expect each of the following standard keyboard shortcuts to perform the action listed in the table below." + }, + { + "type": "table", + "rows": [ + [ + "Primary key", + "Keyboard shortcut", + "Action" + ], + [ + "Space", + "Command-Space", + "Show or hide the Spotlight search field." + ], + [ + "", + "Shift-Command-Space", + "Varies." + ], + [ + "", + "Option-Command-Space", + "Show the Spotlight search results window." + ], + [ + "", + "Control-Command-Space", + "Show the Special Characters window." + ], + [ + "Tab", + "Shift-Tab", + "Navigate through controls in a reverse direction." + ], + [ + "", + "Command-Tab", + "Move forward to the next most recently used app in a list of open apps." + ], + [ + "", + "Shift-Command-Tab", + "Move backward through a list of open apps (sorted by recent use)." + ], + [ + "", + "Control-Tab", + "Move focus to the next group of controls in a dialog or the next table (when Tab moves to the next cell)." + ], + [ + "", + "Control-Shift-Tab", + "Move focus to the previous group of controls." + ], + [ + "Esc", + "Esc", + "Cancel the current action or process." + ], + [ + "Esc", + "Option-Command-Esc", + "Open the Force Quit dialog." + ], + [ + "Eject", + "Control-Command-Eject", + "Quit all apps (after changes have been saved to open documents) and restart the computer." + ], + [ + "", + "Control-Option-Command-Eject", + "Quit all apps (after changes have been saved to open documents) and shut the computer down." + ], + [ + "F1", + "Control-F1", + "Toggle full keyboard access on or off." + ], + [ + "F2", + "Control-F2", + "Move focus to the menu bar." + ], + [ + "F3", + "Control- F3", + "Move focus to the Dock." + ], + [ + "F4", + "Control-F4", + "Move focus to the active (or next) window." + ], + [ + "", + "Control-Shift-F4", + "Move focus to the previously active window." + ], + [ + "F5", + "Control-F5", + "Move focus to the toolbar." + ], + [ + "", + "Command-F5", + "Turn VoiceOver on or off." + ], + [ + "F6", + "Control-F6", + "Move focus to the first (or next) panel." + ], + [ + "", + "Control-Shift-F6", + "Move focus to the previous panel." + ], + [ + "F7", + "Control-F7", + "Temporarily override the current keyboard access mode in windows and dialogs." + ], + [ + "F8", + "", + "Varies." + ], + [ + "F9", + "", + "Varies." + ], + [ + "F10", + "", + "Varies." + ], + [ + "F11", + "", + "Show desktop." + ], + [ + "F12", + "", + "Hide or display Dashboard." + ], + [ + "Grave accent (`)", + "Command-Grave accent", + "Activate the next open window in the frontmost app." + ], + [ + "", + "Shift-Command-Grave accent", + "Activate the previous open window in the frontmost app." + ], + [ + "", + "Option-Command-Grave accent", + "Move focus to the window drawer." + ], + [ + "Hyphen (-)", + "Command-Hyphen", + "Decrease the size of the selection." + ], + [ + "", + "Option-Command-Hyphen", + "Zoom out when screen zooming is on." + ], + [ + "Left bracket ({)", + "Command-Left bracket", + "Left-align a selection." + ], + [ + "Right bracket (})", + "Command-Right bracket", + "Right-align a selection." + ], + [ + "Pipe (|)", + "Command-Pipe", + "Center-align a selection." + ], + [ + "Colon (:)", + "Command-Colon", + "Display the Spelling window." + ], + [ + "Semicolon (;)", + "Command-Semicolon", + "Find misspelled words in the document." + ], + [ + "Comma (,)", + "Command-Comma", + "Open the app’s settings window." + ], + [ + "", + "Control-Option-Command-Comma", + "Decrease screen contrast." + ], + [ + "Period (.)", + "Command-Period", + "Cancel an operation." + ], + [ + "", + "Control-Option-Command-Period", + "Increase screen contrast." + ], + [ + "Question mark (?)", + "Command-Question mark", + "Open the app’s Help menu." + ], + [ + "Forward slash (/)", + "Option-Command-Forward slash", + "Turn font smoothing on or off." + ], + [ + "Equal sign (=)", + "Shift-Command-Equal sign", + "Increase the size of the selection." + ], + [ + "", + "Option-Command-Equal sign", + "Zoom in when screen zooming is on." + ], + [ + "3", + "Shift-Command-3", + "Capture the screen to a file." + ], + [ + "", + "Control-Shift-Command-3", + "Capture the screen to the Clipboard." + ], + [ + "4", + "Shift-Command-4", + "Capture a selection to a file." + ], + [ + "", + "Control-Shift-Command-4", + "Capture a selection to the Clipboard." + ], + [ + "8", + "Option-Command-8", + "Turn screen zooming on or off." + ], + [ + "", + "Control-Option-Command-8", + "Invert the screen colors." + ], + [ + "A", + "Command-A", + "Select every item in a document or window, or all characters in a text field." + ], + [ + "", + "Shift-Command-A", + "Deselect all selections or characters." + ], + [ + "B", + "Command-B", + "Boldface the selected text or toggle boldfaced text on and off." + ], + [ + "C", + "Command-C", + "Copy the selection to the Clipboard." + ], + [ + "", + "Shift-Command-C", + "Display the Colors window." + ], + [ + "", + "Option-Command-C", + "Copy the style of the selected text." + ], + [ + "", + "Control-Command-C", + "Copy the formatting settings of the selection and store on the Clipboard." + ], + [ + "D", + "Option-Command-D", + "Show or hide the Dock." + ], + [ + "", + "Control-Command-D", + "Display the definition of the selected word in the Dictionary app." + ], + [ + "E", + "Command-E", + "Use the selection for a find operation." + ], + [ + "F", + "Command-F", + "Open a Find window." + ], + [ + "", + "Option-Command-F", + "Jump to the search field control." + ], + [ + "", + "Control-Command-F", + "Enter full screen." + ], + [ + "G", + "Command-G", + "Find the next occurrence of the selection." + ], + [ + "", + "Shift-Command-G", + "Find the previous occurrence of the selection." + ], + [ + "H", + "Command-H", + "Hide the windows of the currently running app." + ], + [ + "", + "Option-Command-H", + "Hide the windows of all other running apps." + ], + [ + "I", + "Command-I", + "Italicize the selected text or toggle italic text on or off." + ], + [ + "", + "Command-I", + "Display an Info window." + ], + [ + "", + "Option-Command-I", + "Display an inspector window." + ], + [ + "J", + "Command-J", + "Scroll to a selection." + ], + [ + "M", + "Command-M", + "Minimize the active window to the Dock." + ], + [ + "", + "Option-Command-M", + "Minimize all windows of the active app to the Dock." + ], + [ + "N", + "Command-N", + "Open a new document." + ], + [ + "O", + "Command-O", + "Display a dialog for choosing a document to open." + ], + [ + "P", + "Command-P", + "Display the Print dialog." + ], + [ + "", + "Shift-Command-P", + "Display the Page Setup dialog." + ], + [ + "Q", + "Command-Q", + "Quit the app." + ], + [ + "", + "Shift-Command-Q", + "Log out the person currently logged in." + ], + [ + "", + "Option-Shift-Command-Q", + "Log out the person currently logged in without confirmation." + ], + [ + "S", + "Command-S", + "Save a new document or save a version of a document." + ], + [ + "", + "Shift-Command-S", + "Duplicate the active document or initiate a Save As." + ], + [ + "T", + "Command-T", + "Display the Fonts window." + ], + [ + "", + "Option-Command-T", + "Show or hide a toolbar." + ], + [ + "U", + "Command-U", + "Underline the selected text or turn underlining on or off." + ], + [ + "V", + "Command-V", + "Paste the Clipboard contents at the insertion point." + ], + [ + "", + "Shift-Command-V", + "Paste as (Paste as Quotation, for example)." + ], + [ + "", + "Option-Command-V", + "Apply the style of one object to the selection." + ], + [ + "", + "Option-Shift-Command-V", + "Paste the Clipboard contents at the insertion point and apply the style of the surrounding text to the inserted object." + ], + [ + "", + "Control-Command-V", + "Apply formatting settings to the selection." + ], + [ + "W", + "Command-W", + "Close the active window." + ], + [ + "", + "Shift-Command-W", + "Close a file and its associated windows." + ], + [ + "", + "Option-Command-W", + "Close all windows in the app." + ], + [ + "X", + "Command-X", + "Remove the selection and store on the Clipboard." + ], + [ + "Z", + "Command-Z", + "Undo the previous operation." + ], + [ + "", + "Shift-Command-Z", + "Redo (when Undo and Redo are separate commands rather than toggled using Command-Z)." + ], + [ + "Right arrow", + "Command-Right arrow", + "Change the keyboard layout to current layout of Roman script." + ], + [ + "", + "Shift-Command-Right arrow", + "Extend selection to the next semantic unit, typically the end of the current line." + ], + [ + "", + "Shift-Right arrow", + "Extend selection one character to the right." + ], + [ + "", + "Option-Shift-Right arrow", + "Extend selection to the end of the current word, then to the end of the next word." + ], + [ + "", + "Control-Right arrow", + "Move focus to another value or cell within a view, such as a table." + ], + [ + "Left arrow", + "Command-Left arrow", + "Change the keyboard layout to current layout of system script." + ], + [ + "", + "Shift-Command-Left arrow", + "Extend selection to the previous semantic unit, typically the beginning of the current line." + ], + [ + "", + "Shift-Left arrow", + "Extend selection one character to the left." + ], + [ + "", + "Option-Shift-Left arrow", + "Extend selection to the beginning of the current word, then to the beginning of the previous word." + ], + [ + "", + "Control-Left arrow", + "Move focus to another value or cell within a view, such as a table." + ], + [ + "Up arrow", + "Shift-Command-Up arrow", + "Extend selection upward in the next semantic unit, typically the beginning of the document." + ], + [ + "", + "Shift-Up arrow", + "Extend selection to the line above, to the nearest character boundary at the same horizontal location." + ], + [ + "", + "Option-Shift-Up arrow", + "Extend selection to the beginning of the current paragraph, then to the beginning of the next paragraph." + ], + [ + "", + "Control-Up arrow", + "Move focus to another value or cell within a view, such as a table." + ], + [ + "Down arrow", + "Shift-Command-Down arrow", + "Extend selection downward in the next semantic unit, typically the end of the document." + ], + [ + "", + "Shift-Down arrow", + "Extend selection to the line below, to the nearest character boundary at the same horizontal location." + ], + [ + "", + "Option-Shift-Down arrow", + "Extend selection to the end of the current paragraph, then to the end of the next paragraph (include the paragraph terminator, such as Return, in cut, copy, and paste operations)." + ], + [ + "", + "Control-Down arrow", + "Move focus to another value or cell within a view, such as a table." + ] + ] + }, + { + "type": "paragraph", + "text": "The system also defines several keyboard shortcuts for use with localized versions of the system, localized keyboards, keyboard layouts, and input methods. These shortcuts don’t correspond directly to menu commands." + }, + { + "type": "table", + "rows": [ + [ + "Keyboard shortcut", + "Action" + ], + [ + "Control-Space", + "Toggle between the current and last input source." + ], + [ + "Control-Option-Space", + "Switch to the next input source in the list." + ], + [ + "[Modifier key]-Command-Space", + "Varies." + ], + [ + "Command-Right arrow", + "Change keyboard layout to current layout of Roman script." + ], + [ + "Command-Left arrow", + "Change keyboard layout to current layout of system script." + ] + ] + } + ] + }, + { + "heading": "Custom keyboard shortcuts", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Define custom keyboard shortcuts for only the most frequently used app-specific commands. People appreciate using keyboard shortcuts for actions they perform frequently, but defining too many new shortcuts can make your app seem difficult to learn." + }, + { + "type": "paragraph", + "text": "Use modifier keys in ways that people expect. For example, pressing Command while dragging moves items as a group, and pressing Shift while drag-resizing constrains resizing to the item’s aspect ratio. In addition, holding an arrow key moves the selected item by the smallest app-defined unit of distance until people release the key." + }, + { + "type": "paragraph", + "text": "Here are the modifier keys and the symbols that represent them." + }, + { + "type": "table", + "rows": [ + [ + "Modifier key", + "Symbol", + "Recommended usage" + ], + [ + "Command", + "", + "Prefer the Command key as the main modifier key in a custom keyboard shortcut." + ], + [ + "Shift", + "", + "Prefer the Shift key as a secondary modifier that complements a related shortcut." + ], + [ + "Option", + "", + "Use the Option modifier sparingly for less-common commands or power features." + ], + [ + "Control", + "", + "Avoid using the Control key as a modifier. The system uses Control in many systemwide features and shortcuts, like moving focus or capturing screenshots." + ] + ] + }, + { + "type": "tip", + "text": "TipSome languages require modifier keys to generate certain characters. For example, on a French keyboard, Option-5 generates the “{“ character. It’s usually safe to use the Command key as a modifier, but avoid using an additional modifier with characters that aren’t available on all keyboards. If you must use a modifier other than Command, prefer using it only with the alphabetic characters." + }, + { + "type": "paragraph", + "text": "List modifier keys in the correct order. If you use more than one modifier key in a custom shortcut, always list them in this order: Control, Option, Shift, Command." + }, + { + "type": "paragraph", + "text": "Avoid adding Shift to a shortcut that uses the upper character of a two-character key. People already understand that they must hold the Shift key to type the upper character of a two-character key, so it’s clearer to simply list the upper character in the shortcut. For example, the keyboard shortcut for Hide Status Bar is Command-Slash, whereas the keyboard shortcut for Help is Command-Question mark, not Shift-Command-Slash." + }, + { + "type": "paragraph", + "text": "Let the system localize and mirror your keyboard shortcuts as needed. The system automatically localizes a shortcut’s primary and modifier keys to support the currently connected keyboard; if your app or game switches to a right-to-left layout, the system automatically mirrors the shortcut. For guidance, see Right to left." + }, + { + "type": "paragraph", + "text": "Avoid creating a new shortcut by adding a modifier to an existing shortcut for an unrelated command. For example, because people are accustomed to using Command-Z for undoing an action, it would be confusing to use Shift-Command-Z as the shortcut for a command that’s unrelated to undo and redo." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In visionOS, an app’s keyboard shortcuts appear in the shortcut interface that displays when people hold the Command key on a connected keyboard. Similar in organization to an app’s menu bar menus on iPad or Mac, the shortcut interface on Apple Vision Pro displays app commands in familiar system-defined menu categories such as File, Edit, and View. Unlike menu bar menus, the shortcut interface displays all relevant categories in one view, listing within each category only available commands that also have shortcuts." + }, + { + "type": "paragraph", + "text": "Write descriptive shortcut titles. Because the shortcut interface displays a flat list of all items in each category, submenu titles aren’t available to provide context for their child items. Make sure each shortcut title is descriptive enough to convey its action without the additional context a submenu title might provide. For developer guidance, see discoverabilityTitle." + }, + { + "type": "paragraph", + "text": "Recognize that people see an overlay when they use a physical keyboard with your visionOS app or game. When people connect a physical keyboard while using your visionOS app or game, the system displays a virtual keyboard overlay that provides typing completion and other controls." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Virtual keyboards" + }, + { + "type": "paragraph", + "text": "Entering data" + }, + { + "type": "paragraph", + "text": "Pointing devices" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "KeyboardShortcut — SwiftUI" + }, + { + "type": "paragraph", + "text": "Input events — SwiftUI" + }, + { + "type": "paragraph", + "text": "Handling key presses made on a physical keyboard — UIKit" + }, + { + "type": "paragraph", + "text": "Mouse, Keyboard, and Trackpad — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Moved game-specific key bindings guidance to the Game controls page." + ], + [ + "June 10, 2024", + "Added game-specific guidance and made organizational updates." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "virtual keyboard", + "url": "/design/human-interface-guidelines/virtual-keyboards" + }, + { + "title": "Game controls", + "url": "/design/human-interface-guidelines/game-controls#Keyboards" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/keyboards#Best-practices" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/focus-and-selection#iPadOS" + }, + { + "title": "custom", + "url": "/design/human-interface-guidelines/keyboards#Custom-keyboard-shortcuts" + }, + { + "title": "Standard keyboard shortcuts", + "url": "/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts" + }, + { + "title": "Right to left", + "url": "/design/human-interface-guidelines/right-to-left" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/keyboards#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/keyboards#visionOS" + }, + { + "title": "menu bar menus", + "url": "/design/human-interface-guidelines/the-menu-bar" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/keyboards#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/keyboards#Related" + }, + { + "title": "Entering data", + "url": "/design/human-interface-guidelines/entering-data" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/keyboards#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/keyboards#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Nearby interactions", + "url": "https://developer.apple.com/design/human-interface-guidelines/nearby-interactions", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A great nearby interaction feels intuitive and natural to people, because it builds on their innate awareness of the world around them. For example, a person playing music on their iPhone can continue listening on their HomePod mini when they bring the devices close together, simply by transferring the audio output from their iPhone to the HomePod mini." + }, + { + "type": "paragraph", + "text": "Nearby interactions are available on devices that support Ultra Wideband technology (to learn more, see Ultra Wideband availability), and rely on the Nearby Interaction framework. Before participating in nearby interaction experiences, people grant permission for their device to interact while they’re using your app. The Nearby Interaction APIs help you preserve people’s privacy by relying on randomly generated device identifiers that last only as long as the interaction session your app initiates." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Consider a task from the perspective of the physical world to find inspiration for a nearby interaction. For example, although people can easily use your app’s UI to transfer a song from their iPhone to their HomePod mini, initiating the transfer by bringing the devices close together makes the task feel rooted in the physical world. Discovering the physical actions that inform the concept of a task can help you create an engaging experience that makes performing it feel easy and natural." + }, + { + "type": "paragraph", + "text": "Use distance, direction, and context to inform an interaction. Although your app may get information from a variety of sources, prioritizing nearby, contextually relevant information can help you deliver experiences that feel organic. For example, if people want to share content with a friend in a crowded room, the iOS share sheet can suggest a likely recipient by using on-device knowledge about the person’s most frequent and recent contacts. Combining this knowledge with information from nearby devices that include the U1 chip can let the share sheet improve the experience by suggesting the closest contact the person is facing." + }, + { + "type": "paragraph", + "text": "Consider how changes in physical distance can guide a nearby interaction. In the physical world, people generally expect their perception of an object to sharpen as they get closer to it. A nearby interaction can mirror this experience by providing feedback that changes with the proximity of an object. For example, when people use iPhone to find an AirTag, the display transitions from a directional arrow to a pulsing circle as they get closer." + }, + { + "type": "paragraph", + "text": "Provide continuous feedback. Continuous feedback reflects the dynamism of the physical world and strengthens the connection between a nearby interaction and the task people are performing. For example, when looking for a lost item in Find My, people get continuous updates that communicate the item’s direction and proximity. Keep people engaged by providing uninterrupted feedback that responds to their movements." + }, + { + "type": "paragraph", + "text": "Consider using multiple feedback types to create a holistic experience. Fluidly transitioning among visual, audible, and haptic feedback can help a nearby interaction’s task feel more engaging and real. Using more than one type of feedback also lets you vary the experience to coordinate with both the task and the current context. For example, while people are interacting with the device screen, visual feedback makes sense; while people are interacting with their environment, audible and haptic feedback often work better." + }, + { + "type": "paragraph", + "text": "Avoid using a nearby interaction as the only way to perform a task. You can’t assume that everyone can experience a nearby interaction, so it’s essential to provide alternative ways to get things done in your app." + } + ] + }, + { + "heading": "Device usage", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Encourage people to hold the device in portrait orientation. Holding a device in landscape can decrease the accuracy and availability of information about the distance and relative direction of other devices. If you support only portrait orientation while your nearby interaction feature runs, prefer giving people implicit, visual feedback on how to hold the device for an optimal experience; when possible, avoid explicitly telling people to hold the device in portrait." + }, + { + "type": "paragraph", + "text": "Design for the device’s directional field of view. Nearby interaction relies on a hardware sensor with a specific field of view similar to that of the Ultra Wide camera in iPhone 11 and later. If a participating device is outside of this field of view, your app might receive information about its distance, but not its relative direction." + }, + { + "type": "paragraph", + "text": "Help people understand how intervening objects can affect the nearby interaction experience in your app. When other people, animals, or sufficiently large objects come between two participating devices, the accuracy or availability of distance and direction information can decrease. Consider adding advice on avoiding this situation to onboarding or tutorial content you present." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iPadOS. Not supported in macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On iPhone, Nearby Interaction APIs provide a peer device’s distance and direction." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Apple Watch, Nearby Interaction APIs provide a peer device’s distance. Also, all watchOS apps participating in a nearby interaction experience must be in the foreground." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Feedback" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Nearby Interaction" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 21, 2023", + "Changed page title from Spatial interactions." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/nearby-interactions#Best-practices" + }, + { + "title": "Device usage", + "url": "/design/human-interface-guidelines/nearby-interactions#Device-usage" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/nearby-interactions#Platform-considerations" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/nearby-interactions#iOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/nearby-interactions#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/nearby-interactions#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/nearby-interactions#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/nearby-interactions#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/nearby-interactions#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/nearby-interactions#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Pointing devices", + "url": "https://developer.apple.com/design/human-interface-guidelines/pointing-devices", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People appreciate the precision and flexibility that pointing devices offer. On a Mac, people typically expect to combine a pointing device with a keyboard as they navigate apps and the system. On iPad and Apple Vision Pro, a pointing device gives people an additional way to interact with apps and content, without replacing touch, eyes, or gestures." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Be consistent when responding to mouse and trackpad gestures. People expect most gestures to work the same throughout the system, regardless of the app or game they’re using. On a Mac, for example, people rely on the “Swipe between pages” gesture to behave the same way whether they’re browsing individual document pages, webpages, or images." + }, + { + "type": "paragraph", + "text": "Avoid redefining systemwide trackpad gestures. Even in a game that uses app-specific gestures in a custom way, people expect systemwide gestures to be available; for example, people expect to make familiar gestures to reveal the Dock or Mission Control in macOS. Remember that Mac users can customize the gestures for performing systemwide actions." + }, + { + "type": "paragraph", + "text": "Provide a consistent experience in your app, whether people are using gestures, eyes, a pointing device, or a keyboard. People expect to move fluidly between multiple types of input, and they don’t want to learn different interactions for each mode or for each app they use." + }, + { + "type": "paragraph", + "text": "Let people use the pointer to reveal and hide controls that automatically minimize or fade out. In iPadOS, for example, people can reveal the minimized Safari toolbar by holding the pointer over it (the toolbar minimizes again when the pointer moves away). People can also move the pointer to reveal or hide playback controls while they watch a full-screen video." + }, + { + "type": "paragraph", + "text": "Provide a consistent experience when people press and hold a modifier key while interacting with objects in your app. For example, if people can duplicate an object by pressing and holding the Option key while they drag that object, ensure the result is the same whether they drag using touch or the pointer." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "iPadOS builds on the traditional pointer experience, automatically adapting the pointer to the current context and providing rich visual feedback at a level of precision that enhances productivity and simplifies common tasks on a touchscreen device. The iPadOS pointing system gives people an additional way to interact with apps and content — it doesn’t replace touch." + }, + { + "type": "paragraph", + "text": "Allow multiple selection in custom views when necessary. In iPadOS 15 and later, people can click and drag the pointer over multiple items to select them. As people use the pointer in this way, it expands into a visible rectangle that selects the items it encompasses. Standard nonlist collection views support this interaction by default; if you want to support multiple selection in custom views, you need to implement it yourself. For developer guidance, see UIBandSelectionInteraction." + }, + { + "type": "paragraph", + "text": "Distinguish between pointer and finger input only if it provides value. For example, a scrubber can give people an additional way to target a location in a video when they’re using the pointer. In this scenario, people can drag the playhead using either the pointer or touch, but they can use the pointer to click a precise seek destination." + } + ] + }, + { + "heading": "Pointer shape and content effects", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "iPadOS integrates the appearance and behavior of both the pointer and the element it moves over, bringing focus to the item the pointer is targeting. You can support the system-provided pointer effects or modify them to suit your experience." + }, + { + "type": "paragraph", + "text": "By default, the pointer’s shape is a circle, but it can display a system-defined or custom shape when people move it over specific elements or regions. For example, the pointer automatically uses the familiar I-beam shape when people move it over a text-entry area." + }, + { + "type": "paragraph", + "text": "With a content effect, the UI element or region beneath the pointer can also change its appearance when people hold the pointer over it. Depending on the type of content effect, the pointer can retain its current shape or transform into a shape that integrates with the element’s new appearance." + }, + { + "type": "paragraph", + "text": "iPadOS defines three content effects that bring focus to different types of interactive elements in your app: highlight, lift, and hover." + }, + { + "type": "paragraph", + "text": "The highlight effect transforms the pointer into a translucent, rounded rectangle that acts as a background for a control and includes a gentle parallax. The subtle highlighting and movement bring focus to the control without distracting people from their task. By default, iPadOS applies the highlight effect to bar buttons, tab bars, segmented controls, and edit menus." + }, + { + "type": "paragraph", + "text": "The lift effect combines a subtle parallax with the appearance of elevation to make an element seem like it’s floating above the screen. As the pointer fades out beneath the element, iPadOS creates the illusion of lift by scaling the element up while adding a shadow below it and a soft specular highlight on top of it. By default, iPadOS applies the lift effect to app icons and to buttons in Control Center." + }, + { + "type": "paragraph", + "text": "Hover is a generic effect that lets you apply custom scale, tint, or shadow values to an element as the pointer moves over it. The hover effect combines your custom values to bring focus to an item, but it doesn’t transform the default pointer shape." + } + ] + }, + { + "heading": "Pointer accessories", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Pointer accessories are visual indicators that help people understand how they can use the pointer to interact with the current UI element. For example, a pointer approaching a resizable element might display small arrows to indicate that the element allows resizing along a certain axis." + }, + { + "type": "paragraph", + "text": "Unlike pointer shapes and content effects, accessories are secondary items that can combine with any pointer to communicate additional information. For developer guidance, see UIPointerAccessory." + }, + { + "type": "paragraph", + "text": "Use clear, simple images to create custom accessories. A pointer accessory is small, so it’s essential to create an image that communicates the pointer interaction without using too many details." + }, + { + "type": "paragraph", + "text": "Consider using the accessory transition to signal a change in an element’s state or behavior. In addition to animating the appearance and disappearance of pointer accessories, the system also animates the transitions among accessory shapes and positions that can accompany content effects. For example, you could communicate that an add action has become unavailable by transitioning the pointer accessory from the plus symbol to the circle.slash symbol." + } + ] + }, + { + "heading": "Pointer magnetism", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "iPadOS helps people use the pointer to target an element by making the element appear to attract the pointer. People can experience this magnetic effect when they move the pointer close to an element and when they flick the pointer toward an element." + }, + { + "type": "paragraph", + "text": "When people move the pointer close to an element, the system starts transforming the pointer’s shape as soon as it reaches the element’s hit region. Because an element’s hit region typically extends beyond its visible boundaries, the pointer begins to transform before it appears to touch the element itself, creating the illusion that the element is pulling the pointer toward it." + }, + { + "type": "paragraph", + "text": "When people flick the pointer toward an element, iPadOS examines the pointer’s trajectory to discover the element that’s the most likely target. When there’s an element in the pointer’s path, the system uses magnetism to pull the pointer toward the element’s center." + }, + { + "type": "paragraph", + "text": "By default, iPadOS applies magnetism to elements that use the lift effect (like app icons) and the highlight effect (like bar buttons), but not to elements that use hover. Because an element that supports hover doesn’t transform the default pointer shape, adding magnetism could be jarring and might make people feel that they’ve lost control of the pointer." + }, + { + "type": "paragraph", + "text": "The system also applies magnetism to text-entry areas, where it can help people avoid skipping to another line if they make unintended vertical movements while they’re selecting text." + } + ] + }, + { + "heading": "Standard pointers and effects", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "When possible, support the system-provided content effects. People quickly become accustomed to the content effects they see throughout the system and generally expect their experience to apply to every app they use. To provide a consistent user experience, align your interactions with the design intent of each effect. Specifically:" + }, + { + "type": "list", + "items": [ + "Use highlight for a small element that has a transparent background.", + "Use lift for a small element that has an opaque background.", + "Use hover for large elements and customize the scale, tint, and shadow attributes as needed (for guidance, see Customizing pointers)." + ] + }, + { + "type": "paragraph", + "text": "Prefer the system-provided pointer appearances for standard buttons and text-entry areas. You can help people feel more comfortable with your app when the pointer behaves in ways they expect." + }, + { + "type": "paragraph", + "text": "Add padding around interactive elements to create comfortable hit regions. You might need to experiment to determine the right size for an element’s hit region. If the hit region is too small, it can make people feel that they have to be extra precise when interacting with the element. On the other hand, when an element’s hit region is too large, people can feel that it takes a lot of effort to pull the pointer away from the element. In general, it works well to add about 12 points of padding around elements that include a bezel; for elements without a bezel, it works well to add about 24 points of padding around the element’s visible edges." + }, + { + "type": "paragraph", + "text": "Create contiguous hit regions for custom bar buttons. If there’s space between the hit regions of adjacent buttons in a bar, people may experience a distracting motion when the pointer reverts briefly to its default shape as it moves between buttons." + }, + { + "type": "paragraph", + "text": "Specify the corner radius of a nonstandard element that receives the lift effect. With the system-provided lift effect, the pointer transforms to match the element’s shape as it fades out. By default, the pointer uses the system-defined corner radius to transform into a rounded rectangle. If your element is a different shape — if it’s a circle, for example — you need to provide the radius so the pointer can animate seamlessly into the shape of the element. For developer guidance, see UIPointerShape.roundedRect(_:radius:)." + } + ] + }, + { + "heading": "Customizing pointers", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Prefer system-provided pointer effects for custom elements that behave like standard elements. When a custom element behaves like a standard one, people generally expect to interact with it using familiar pointer interactions. For example, if buttons in a custom toolbar don’t use the standard highlight effect, people might think they’re broken." + }, + { + "type": "paragraph", + "text": "Use pointer effects in consistent ways throughout your app. For example, if your app helps people draw, provide a similar pointer experience for every drawing area in your app so that people can apply the knowledge they gain in one area to the others." + }, + { + "type": "paragraph", + "text": "Avoid creating gratuitous pointer and content effects. People notice when the appearance of the pointer or the UI element beneath it changes, and they expect the changes to be useful. Creating a purely decorative pointer effect can distract and even irritate people without providing any practical value." + }, + { + "type": "paragraph", + "text": "Keep custom pointer shapes simple. Ideally, the pointer’s shape signals the action people can take in the current context without drawing too much attention to itself. If people don’t instantly understand your custom pointer shape, they’re likely to waste time trying to discover what the shape means." + }, + { + "type": "paragraph", + "text": "Consider enhancing the pointer experience by displaying custom annotations that provide useful information. For example, you could display X and Y values when people hold the pointer over a graphing area in your app. Keynote uses annotations to display the current width and height of a resizable image." + }, + { + "type": "paragraph", + "text": "Avoid displaying instructional text with a pointer. A pointer that displays instructional text can make an app seem complicated and difficult to use. Instead of providing instructions, prioritize clarity and simplicity in your interface, so that people can quickly grasp how to use your app whether they’re using the pointer or touching the screen." + }, + { + "type": "paragraph", + "text": "Consider the interplay of shadow, scale, and element spacing when defining custom hover effects. In general, reserve scaling for elements that can increase in size without crowding nearby elements. For example, scaling doesn’t work well for a table row because a row can’t expand without overlapping adjacent rows. For an element that has little space around it, consider using a hover effect that includes tint, but not scale and shadow. Note that it doesn’t work well to use shadow without including scale, because an unscaled element doesn’t appear to get closer to the viewer even when its shadow implies that it’s elevated above the screen." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "macOS supports a wide range of standard mouse and trackpad interactions that people can customize. For example, when a click or gesture isn’t a primary way to interact with content, people can often turn it on or off based on their current workflow. People can also choose specific regions of a mouse or trackpad to invoke secondary clicks, and select specific finger combinations and movements for certain gestures." + }, + { + "type": "table", + "rows": [ + [ + "Click or gesture", + "Expected behavior", + "Mouse", + "Trackpad" + ], + [ + "Primary click", + "Select or activate an item, such as a file or button.", + "●", + "●" + ], + [ + "Secondary click", + "Reveal contextual menus.", + "●", + "●" + ], + [ + "Scrolling", + "Move content up, down, left, or right within a view.", + "●", + "●" + ], + [ + "Smart zoom", + "Zoom in or out on content, such as a web page or PDF.", + "●", + "●" + ], + [ + "Swipe between pages", + "Navigate forward or backward between individually displayed pages.", + "●", + "●" + ], + [ + "Swipe between full-screen apps", + "Navigate forward or backward between full-screen apps and spaces.", + "●", + "●" + ], + [ + "Mission Control (double-tap the mouse with two fingers or swipe up on the trackpad with three or four fingers)", + "Activate Mission Control.", + "●", + "●" + ], + [ + "Lookup and data detectors (force click with one finger or tap with three fingers)", + "Display a lookup window above selected content.", + "", + "●" + ], + [ + "Tap to click", + "Perform the primary click action using a tap rather than a click.", + "", + "●" + ], + [ + "Force click", + "Click then press firmly to display a Quick Look window or lookup window above selected content. Apply a variable amount of pressure to affect pressure-sensitive controls, such as variable speed media controls.", + "", + "●" + ], + [ + "Zoom in or out (pinch with two fingers)", + "Zoom in or out.", + "", + "●" + ], + [ + "Rotate (move two fingers in a circular motion)", + "Rotate content, such as an image.", + "", + "●" + ], + [ + "Notification Center (swipe from the edge of the trackpad)", + "Display Notification Center.", + "", + "●" + ], + [ + "App Exposé (swipe down with three or four fingers)", + "Display the current app’s windows in Exposé.", + "", + "●" + ], + [ + "Launchpad (pinch with thumb and three fingers)", + "Display the Launchpad.", + "", + "●" + ], + [ + "Show Desktop (spread with thumb and three fingers)", + "Slide all windows out of the way to reveal the desktop.", + "", + "●" + ] + ] + } + ] + }, + { + "heading": "Pointers", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "macOS offers a variety of standard pointer styles, which your app can use to communicate the interactive state of an interface element or the result of a drag operation." + }, + { + "type": "table", + "rows": [ + [ + "Pointer", + "Name", + "Meaning", + "AppKit API" + ], + [ + "", + "Arrow", + "Standard pointer for selecting and interacting with content and interface elements.", + "arrow" + ], + [ + "", + "Closed hand", + "Dragging to reposition the display of content within a view—for example, dragging a map around in Maps.", + "closedHand" + ], + [ + "", + "Contextual menu", + "A contextual menu is available for the content below the pointer. This pointer is generally shown only when the Control key is pressed.", + "contextualMenu" + ], + [ + "", + "Crosshair", + "Precise rectangular selection is possible, such as when viewing an image in Preview.", + "crosshair" + ], + [ + "", + "Disappearing item", + "A dragged item will disappear when dropped. If the item references an original item, the original is unaffected. For example, when dragging a mailbox out of the favorites bar in Mail, the original mailbox isn’t removed.", + "disappearingItem" + ], + [ + "", + "Drag copy", + "Duplicates a dragged—not moved—item when dropped into the destination. Appears when pressing the Option key during a drag operation.", + "dragCopy" + ], + [ + "", + "Drag link", + "During a drag and drop operation, creates an alias of the selected file when dropped. The alias points to the original file, which remains unmoved. Appears when pressing the Option and Command keys during a drag operation.", + "dragLink" + ], + [ + "", + "Horizontal I beam", + "Selection and insertion of text is possible in a horizontal layout, such as a TextEdit or Pages document.", + "iBeam" + ], + [ + "", + "Open hand", + "Dragging to reposition content within a view is possible.", + "openHand" + ], + [ + "", + "Operation not allowed", + "A dragged item can’t be dropped in the current location.", + "operationNotAllowed" + ], + [ + "", + "Pointing hand", + "The content beneath the pointer is a URL link to a webpage, document, or other item.", + "pointingHand" + ], + [ + "", + "Resize down", + "Resize or move a window, view, or element downward.", + "resizeDown" + ], + [ + "", + "Resize left", + "Resize or move a window, view, or element to the left.", + "resizeLeft" + ], + [ + "", + "Resize left/right", + "Resize or move a window, view, or element to the left or right.", + "resizeLeftRight" + ], + [ + "", + "Resize right", + "Resize or move a window, view, or element to the right.", + "resizeRight" + ], + [ + "", + "Resize up", + "Resize or move a window, view, or element upward.", + "resizeUp" + ], + [ + "", + "Resize up/down", + "Resize or move a window, view, or element upward or downward.", + "resizeUpDown" + ], + [ + "", + "Vertical I beam", + "Selection and insertion of text is possible in a vertical layout.", + "iBeamCursorForVerticalLayout" + ] + ] + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In visionOS, people can attach an external pointing device or keyboard, and use both devices while they continue to use their eyes and hands. If people look at an element and then move the pointer, the system brings focus to the element under the pointer. Your app doesn’t have to do anything to support this behavior." + }, + { + "type": "paragraph", + "text": "When a pointing device is attached, the area people are looking at determines the pointer’s context. For example, when people shift their eyes from one window to another, the pointer’s context seamlessly transitions to the new window." + }, + { + "type": "paragraph", + "text": "When people use an attached pointing device that supports gestures, like a trackpad or mouse, the pointer hides while people are gesturing, minimizing visual distraction. In this scenario, the pointer remains hidden until people move it, when it reappears in the location they’re looking at." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Entering data" + }, + { + "type": "paragraph", + "text": "Keyboards" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Input events — SwiftUI" + }, + { + "type": "paragraph", + "text": "Pointer interactions — UIKit" + }, + { + "type": "paragraph", + "text": "Mouse, Keyboard, and Trackpad — 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/pointing-devices#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/pointing-devices#Platform-considerations" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/pointing-devices#iPadOS" + }, + { + "title": "Pointer shape and content effects", + "url": "/design/human-interface-guidelines/pointing-devices#Pointer-shape-and-content-effects" + }, + { + "title": "Pointer accessories", + "url": "/design/human-interface-guidelines/pointing-devices#Pointer-accessories" + }, + { + "title": "Pointer magnetism", + "url": "/design/human-interface-guidelines/pointing-devices#Pointer-magnetism" + }, + { + "title": "Standard pointers and effects", + "url": "/design/human-interface-guidelines/pointing-devices#Standard-pointers-and-effects" + }, + { + "title": "Customizing pointers", + "url": "/design/human-interface-guidelines/pointing-devices#Customizing-pointers" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/pointing-devices#macOS" + }, + { + "title": "Pointers", + "url": "/design/human-interface-guidelines/pointing-devices#Pointers" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/pointing-devices#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/pointing-devices#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/pointing-devices#Related" + }, + { + "title": "Entering data", + "url": "/design/human-interface-guidelines/entering-data" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/pointing-devices#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/pointing-devices#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/pointing-devices#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Remotes", + "url": "https://developer.apple.com/design/human-interface-guidelines/remotes", + "category": "inputs", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In addition to several specific buttons, the Siri Remote combines a clickpad and touch surface to support familiar gestures like swipe and press that people use to navigate tvOS apps, browse channels and content, play and pause media, and make selections." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer using standard gestures to perform standard actions. Unless people are actively playing a game, they expect the remote to behave in standard ways in every app they use. Redefining or repurposing standard remote behaviors can cause confusion and add complexity to your experience. For guidance, see Gestures." + }, + { + "type": "paragraph", + "text": "Be consistent with the tvOS focus experience. The focus experience forges a strong connection between people and the content they’re viewing. Reinforce this link in your app by ensuring that you combine gestures with the focus experience in ways that are familiar to people, such as always moving focus in the same direction as the gesture." + }, + { + "type": "paragraph", + "text": "Provide clear feedback that shows people what happens when they make gestures in your app. For example, lightly resting a thumb on the remote shows people where to swipe down so that they can reveal an info area." + }, + { + "type": "paragraph", + "text": "Define new gestures only when it makes sense in your app. Within gameplay, for example, custom gestures can be a fun part of the experience. In most other situations, people expect to use standard gestures and may not appreciate having to discover or remember new ones." + }, + { + "type": "paragraph", + "text": "Differentiate between press and tap, and avoid responding to an inadvertent tap. Pressing is an intentional action, and it works well for choosing a button, confirming a selection, and initiating an action during gameplay. Tap gestures are fine for navigation or showing additional information, but keep in mind that people might cause an inadvertent tap when they rest a thumb on the remote, pick it up, move it around, or hand it to someone else, so it often works well to avoid responding to taps during live video playback." + }, + { + "type": "paragraph", + "text": "Consider using the position of a tap to aid with navigation or gameplay. The remote can differentiate between up, down, left, and right tap gestures on the touch surface. Respond to positional taps only if it makes sense in the context of your app and if such behavior is intuitive and discoverable." + }, + { + "type": "paragraph", + "text": "In almost all cases, open the parent of the current screen when people press the Back button. At the top level of an app or game, the parent is the Apple TV Home Screen; within an app, the parent is defined by the app hierarchy, and isn’t necessarily the previous screen. The exception to this standard behavior is when people are actively playing a game, where it can be easy to accidentally press the Back button repeatedly. To avoid disrupting gameplay in this scenario, respond to the Back button by opening an in-game pause menu that lets people use a different interaction to navigate back to the game’s main menu. When the in-game pause menu is open, respond to a Back-button press by closing the menu and resuming the game. Note that people press and hold the Back button to go to the Home Screen from any location. For guidance, see Buttons." + }, + { + "type": "paragraph", + "text": "Respond correctly to the Play/Pause button during media playback. When playing music or video, people expect pressing the Play/Pause button to play, pause, or resume playback." + } + ] + }, + { + "heading": "Gestures", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The clickpad’s touch surface detects swipes and presses." + }, + { + "type": "paragraph", + "text": "Swipe. Swiping lets people scroll effortlessly through large numbers of items with movement that starts fast and then slows down, based on the strength of the swipe. When people swipe up or down on the edge of the remote, they can speed through items very quickly." + }, + { + "type": "paragraph", + "text": "Press. People press to activate a control or select an item. Also, people press before swiping to activate scrubbing mode." + } + ] + }, + { + "heading": "Buttons", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Ensure that your app or game responds to specific presses in the following ways." + }, + { + "type": "table", + "rows": [ + [ + "Button or area", + "Expected behavior in an app", + "Expected behavior in a game" + ], + [ + "Touch surface (swipe)", + "Navigates. Changes focus.", + "Performs directional pad behavior." + ], + [ + "Touch surface (press)", + "Activates a control or an item. Navigates deeper.", + "Performs primary button behavior." + ], + [ + "Back", + "Returns to previous screen. Exits to Apple TV Home Screen.", + "Pauses/resumes gameplay. Returns to previous screen, exits to main game menu, or exits to Apple TV Home Screen." + ], + [ + "Play/Pause", + "Activates media playback. Pauses/resumes media playback.", + "Performs secondary button behavior. Skips intro video." + ] + ] + } + ] + }, + { + "heading": "Compatible remotes", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Some remotes that are compatible with Apple TV include buttons for browsing live TV or other channel-based content. For example, a remote might include a button people can use to open an electronic program guide (EPG) and other buttons they can use to browse the guide or change channels. For developer guidance, see Providing Channel Navigation; for design guidance, see EPG experience." + }, + { + "type": "paragraph", + "text": "If your live-viewing app provides an EPG, respond to a remote’s EPG-browsing buttons in ways people expect. When people press a “guide” or “browse” button, they expect your EPG to open. While they’re viewing your EPG, people expect to navigate through it by pressing a “page up” or “page down” button. Avoid responding to these buttons in other ways while people are browsing the EPG. On the Siri Remote and compatible remotes, people can also tap on the upper or lower area of the Touch surface to browse the EPG. If your app doesn’t support an EPG experience, the system routes these button presses to the default guide app on the viewer’s device." + }, + { + "type": "paragraph", + "text": "While your content plays, respond to a compatible remote’s “page up” or “page down” button by changing the channel. People expect these buttons to behave differently when they switch between viewing content and browsing an EPG." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, iPadOS, macOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use your Siri Remote or Apple TV Remote with Apple TV" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/remotes#Best-practices" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/remotes#Gestures" + }, + { + "title": "focus experience", + "url": "/design/human-interface-guidelines/focus-and-selection" + }, + { + "title": "Buttons", + "url": "/design/human-interface-guidelines/remotes#Buttons" + }, + { + "title": "Compatible remotes", + "url": "/design/human-interface-guidelines/remotes#Compatible-remotes" + }, + { + "title": "EPG experience", + "url": "/design/human-interface-guidelines/live-viewing-apps#EPG-experience" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/remotes#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/remotes#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/remotes#Related" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/data/categories/patterns.json b/data/categories/patterns.json new file mode 100644 index 0000000..bd88839 --- /dev/null +++ b/data/categories/patterns.json @@ -0,0 +1,6305 @@ +{ + "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": "patterns" + }, + "name": "Patterns", + "articles": [ + { + "title": "Charting data", + "url": "https://developer.apple.com/design/human-interface-guidelines/charting-data", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Charts provide efficient ways to communicate complex information without requiring people to read and interpret a lot of text. The graphical nature of charts also gives you additional opportunities to express the personality of your experience and add visual interest to your interface. To learn about the components you use to create a chart, see Charts." + }, + { + "type": "paragraph", + "text": "A chart can range from a simple graphic that provides glanceable information to a rich, interactive experience that can form the centerpiece of your app and encourage people to explore the data from various perspectives. Whether simple or complex, you can use charts to help people perform data-driven tasks that are important to them, such as:" + }, + { + "type": "list", + "items": [ + "Analyzing trends based on historical or predicted values", + "Visualizing the current state of a process, system, or quantity that changes over time", + "Evaluating different items — or the same item at different times — by comparing data across multiple categories" + ] + }, + { + "type": "paragraph", + "text": "Not every collection of data needs to be displayed in a chart. If you simply need to provide data — and you don’t need to convey information about it or help people analyze it — consider offering the data in other ways, such as in a list or table that people can scroll, search, and sort." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use a chart when you want to highlight important information about a dataset. Charts are visually prominent, so they tend to draw people’s attention. Take advantage of this prominence by clearly communicating what people can learn from the data they care about." + }, + { + "type": "paragraph", + "text": "Keep a chart simple, letting people choose when they want additional details. Resist the temptation to pack as much data as possible into a chart. Too much data can make a chart visually overwhelming and difficult to use, obscuring the relationships and other information you want to convey. If you have a lot of data to present — or a lot of functionality to provide — consider giving people a way to reveal it gradually. For example, you might let people choose to view different levels of detail or subsets of data to match their interest. To help people learn how to use an interactive chart, you might offer several versions of the chart, each with more functionality than the last." + }, + { + "type": "paragraph", + "text": "Make every chart in your app accessible. A chart communicates visually through graphical representations of data and visual descriptions. In addition to the visual descriptions you display, it’s crucial to provide both accessibility labels that describe chart values and components, and accessibility elements that help people interact with the chart. For guidance, see Enhancing the accessibility of a chart." + } + ] + }, + { + "heading": "Designing effective charts", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In general, prefer using common chart types. People tend to be familiar with common chart types — such as bar charts and line charts — so using one of these types in your app can make it more likely that people will already know how to read your chart. For guidance, see Charts." + }, + { + "type": "paragraph", + "text": "If you need to create a chart that presents data in a novel way, help people learn how to interpret the chart. For example, when a Watch pairs with iPhone, Activity introduces the Activity rings by animating them individually, showing people how each ring maps to the move, exercise, and stand metrics." + }, + { + "type": "paragraph", + "text": "Examine the data from multiple levels or perspectives to find details you can display to enhance the chart. For example, viewing the data from a macro level can help you determine high-level summaries that people might be interested in, like totals or averages. From a mid-level perspective, you might find ways to help people identify useful subsets of the data, whereas examining individual data points might help you find ways to draw people’s attention to specific values or items. Displaying information that helps people view the chart from various perspectives can encourage them to engage with it." + }, + { + "type": "paragraph", + "text": "Aid comprehension by adding descriptive text to the chart. Descriptive text titles, subtitles, and annotations help emphasize the most important information in a chart and can highlight actionable takeaways. You can also display brief descriptive text that serves as a headline or summary for a chart, helping people grasp essential information at a glance. For example, Weather displays text that summarizes the information people need right now — such as “Chance of light rain in the next hour” — above the scrolling list of hourly forecasts for the next 24 hours. Although a descriptive headline or summary can make a chart more accessible, it doesn’t take the place of accessibility labels." + }, + { + "type": "paragraph", + "text": "Match the size of a chart to its functionality, topic, and level of detail. In general, a chart needs to be large enough to comfortably display the details you need to include and expansive enough for the interactivity you want to support. For example, you always want to make it easy for people to read a chart’s details and descriptive text — like labels and annotations — but you might also want to give people enough room to change the scope of a chart or investigate the data from different perspectives. On the other hand, you might want to use a small chart to offer glanceable information about an individual item or to provide a snapshot or preview of a larger version of the chart that people can reveal in a different view." + }, + { + "type": "paragraph", + "text": "Prefer consistency across multiple charts, deviating only when you need to highlight differences. If multiple charts in your app serve a similar purpose, you generally don’t want to imply that the charts are unrelated by using a different type or style for each one. Also, using a consistent visual approach for the charts in your app lets people use what they learn about one chart to help them understand another. Consider using different chart types and styles when you need to highlight meaningful differences between charts." + }, + { + "type": "paragraph", + "text": "Maintain continuity among multiple charts that use the same data. When you use multiple charts to help people explore one dataset from different perspectives, it’s important to use one chart type and consistent colors, annotations, layouts, and descriptive text to signal that the dataset remains the same. For example, the Health Trends screen shows small charts that each use a specific visual style to depict a recent trend in an area like steps or resting heart rate. When people choose a chart to reveal all their data in that area, the expanded version uses the same style, colors, marks, and annotations to strengthen the relationship between the versions." + } + ] + }, + { + "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": "Charts" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Swift Charts" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 23, 2022", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Charts", + "url": "/design/human-interface-guidelines/charts" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/charting-data#Best-practices" + }, + { + "title": "Enhancing the accessibility of a chart", + "url": "/design/human-interface-guidelines/charts#Enhancing-the-accessibility-of-a-chart" + }, + { + "title": "Designing effective charts", + "url": "/design/human-interface-guidelines/charting-data#Designing-effective-charts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/charting-data#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/charting-data#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/charting-data#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/charting-data#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/charting-data#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/charting-data#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Collaboration and sharing", + "url": "https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "System interfaces and the Messages app can help you provide consistent and convenient ways for people to collaborate and share. For example, people can share content or begin a collaboration by dropping a document into a Messages conversation or selecting a destination in the familiar share sheet." + }, + { + "type": "paragraph", + "text": "After a collaboration begins, people can use the Collaboration button in your app to communicate with others, perform custom actions, and manage details. In addition, people can receive Messages notifications when collaborators mention them, make changes, join, or leave." + }, + { + "type": "paragraph", + "text": "You can take advantage of Messages integration and the system-provided sharing interfaces whether you implement collaboration and sharing through CloudKit, iCloud Drive, or a custom solution. To offer these features when you use a custom collaboration infrastructure, make sure your app also supports universal links (for developer guidance, see Supporting universal links in your app)." + }, + { + "type": "paragraph", + "text": "In addition to helping people share and collaborate on documents, visionOS supports immersive sharing experiences through SharePlay. For guidance, see SharePlay." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Place the Share button in a convenient location, like a toolbar, to make it easy for people to start sharing or collaborating. In iOS 16, the system-provided share sheet includes ways to choose a file-sharing method and set permissions for a new collaboration; iPadOS 16 and macOS 13 introduce similar appearance and functionality in the sharing popover. In your SwiftUI app, you can also enable sharing by presenting a share link that opens the system-provided share sheet when people choose it; for developer guidance, see ShareLink." + }, + { + "type": "paragraph", + "text": "If necessary, customize the share sheet or sharing popover to offer the types of file sharing your app supports. If you use CloudKit, you can add support for sending a copy of a file by passing both the file and your collaboration object to the share sheet. Because the share sheet has built-in support for multiple items, it automatically detects the file and makes the “send copy” functionality available. With iCloud Drive, your collaboration object supports “send copy” functionality by default. For custom collaboration, you can support “send copy” functionality in the share sheet by including a file — or a plain text representation of it — in your collaboration object." + }, + { + "type": "paragraph", + "text": "Write succinct phrases that summarize the sharing permissions you support. For example, you might write phrases like “Only invited people can edit” or “Everyone can make changes.” The system uses your permission summary in a button that reveals a set of sharing options that people use to define the collaboration." + }, + { + "type": "paragraph", + "text": "Provide a set of simple sharing options that streamline collaboration setup. You can customize the view that appears when people choose the permission summary button to provide choices that reflect your collaboration functionality. For example, you might offer options that let people specify who can access the content and whether they can edit it or just read it, and whether collaborators can add new participants. Keep the number of custom choices to a minimum and group them in ways that help people understand them at a glance." + }, + { + "type": "paragraph", + "text": "Prominently display the Collaboration button as soon as collaboration starts. The system-provided Collaboration button reminds people that the content is shared and identifies who’s sharing it. Because the Collaboration button typically appears after people interact with the share sheet or sharing popover, it works well to place it next to the Share button." + }, + { + "type": "paragraph", + "text": "Provide custom actions in the collaboration popover only if needed. Choosing the Collaboration button in your app reveals a popover that consists of three sections. The top section lists collaborators and provides communication buttons that can open Messages or FaceTime, the middle section contains your custom items, and the bottom section displays a button people use to manage the shared file. You don’t want to overwhelm people with too much information, so it’s crucial to offer only the most essential items that people need while they use your app to collaborate. For example, Notes summarizes the most recent updates and provides buttons that let people get more information about the updates or view more activities." + }, + { + "type": "paragraph", + "text": "If it makes sense in your app, customize the title of the modal view’s collaboration-management button. People choose this button — titled “Manage Shared File” by default — to reveal the collaboration-management view where they can change settings and add or remove collaborators. If you use CloudKit sharing, the system provides a management view for you; otherwise, you create your own." + }, + { + "type": "paragraph", + "text": "Consider posting collaboration event notifications in Messages. Choose the type of event that occurred — such as a change in the content or the collaboration membership, or the mention of a participant — and include a universal link people can use to open the relevant view in your app. For developer guidance, see SWHighlightEvent." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or macOS. Not available in tvOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "By default, the system supports screen sharing for an app running in the Shared Space by streaming the current window to other collaborators. If one person transitions the app to a Full Space while sharing is in progress, the system pauses the stream for other people until the app returns to the Shared Space. For guidance, see Immersive experiences." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In your SwiftUI app running in watchOS, use ShareLink to present the system-provided share sheet." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Activity views" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Shared with You" + }, + { + "type": "paragraph", + "text": "ShareLink — SwiftUI" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Added artwork illustrating button placement and various types of collaboration permissions." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "September 14, 2022", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "SharePlay", + "url": "/design/human-interface-guidelines/shareplay" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#visionOS" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Related" + }, + { + "title": "Activity views", + "url": "/design/human-interface-guidelines/activity-views" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/collaboration-and-sharing#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Drag and drop", + "url": "https://developer.apple.com/design/human-interface-guidelines/drag-and-drop", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "To perform drag and drop, people select content in one location, called the source, and drop it in another, called the destination. These locations can be in the same container — like a text view — or in different containers, like text views on opposite sides of a split view, or even in different apps." + }, + { + "type": "paragraph", + "text": "Depending on various factors, the drag and drop action might move the selected content to the destination or copy it. After a successful drop, moved content exists only in the destination; copied content exists in both locations. As a general rule, dropping selected content within the same container moves it, whereas dropping content in a different container copies it. Dragging and dropping content between apps always results in a copy." + }, + { + "type": "paragraph", + "text": "People use different interactions to perform drag and drop depending on platform. For example:" + }, + { + "type": "list", + "items": [ + "In visionOS, people pinch and hold a virtual object while dragging it to a new location in any direction, including along the z-axis.", + "iOS and iPadOS support drag and drop through gestures on the touchscreen, interactions with a pointing device, and through full keyboard-access mode.", + "Universal Control lets people drag content between their Mac and iPad.", + "On a Mac, people can interact with a pointing device, use full keyboard access mode, or use VoiceOver to perform drag and drop." + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As much as possible, support drag and drop throughout your app. Most people are familiar with drag and drop and they often try it everywhere. When you use system-provided components — such as text fields and text views — you get built-in support for drag and drop." + }, + { + "type": "paragraph", + "text": "Offer alternative ways to accomplish drag-and-drop actions. Sometimes, drag-and-drop operations are inconvenient or impossible for people to perform, so it’s important to provide other ways to do the same things. For example, you can include menu commands that people can use to copy an item and move it to another location. In iOS and iPadOS, you can use accessibility APIs to identify sources and destinations so that people can use assistive technologies to drag and drop in your app (for developer guidance, see accessibilityDragSourceDescriptors and accessibilityDropPointDescriptors)." + }, + { + "type": "paragraph", + "text": "Determine when dragging and dropping content within your app results in a move or a copy. In general, a move makes sense when the source and destination containers are the same — such as dragging text from one location to another within a document — and a copy makes sense when they’re different, like dragging an image from one document to another. Before you change these defaults, consider the behavior that most people expect and prefer the one that is least likely to result in frustration or data loss." + }, + { + "type": "paragraph", + "text": "Support multi-item drag and drop when it makes sense. People appreciate the convenience of dragging a group of items to a destination, instead of dragging each item separately. In iOS, iPadOS, macOS, and visionOS, people can select multiple items and drag them as a group; macOS also lets people select multiple items from several apps and drag them as a group. In iPadOS, people can select an item, start dragging it, and add other items to the group without stopping the drag operation." + }, + { + "type": "paragraph", + "text": "Prefer letting people undo a drag-and-drop operation. Sometimes, people inadvertently drop content in the wrong destination, so they appreciate being able to undo the action and return to their previous state. You might also be able to help people avoid mistakes by asking for confirmation before completing a drag-and-drop operation that can’t be undone. In macOS, for example, the Finder asks for confirmation when people drag a file into a write-only folder because they won’t be able to open the folder and remove the dropped item. In some situations, it might make sense to provide a way to reverse the results of drag and drop when people can’t undo it. For example, Photos lets people cancel photo sharing after dropping a photo into a shared photo stream." + }, + { + "type": "paragraph", + "text": "Consider offering multiple versions of dragged content, ordered from highest to lowest fidelity. By providing multiple alternatives, the destination can choose the highest quality version it can accept. For example, if people can drag a line drawing they created in your app, you could offer a PDF vector representation, a lossless PNG image with transparency, and a lossy JPEG image without transparency, in that order. Another example is an app that uses rich, complicated objects, like charts. This app might offer the native chart object followed by a simpler version — like an image of the chart — for destinations that don’t support chart objects." + }, + { + "type": "paragraph", + "text": "Consider supporting spring loading. Spring loading lets people activate certain controls, like buttons and segmented controls, by dragging selected content over them. For example, Calendar lets people drag a selected event over the day, week, month, or year segments in the toolbar, giving them a convenient way to move the event to a different date. On a Mac equipped with a Magic Trackpad, a button or segmented control can activate when people force-click it while continuing to hold the content; on iPad, these components can activate when people hover over them while holding the content." + } + ] + }, + { + "heading": "Providing feedback", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Drag and drop is a dynamic process that can result in multiple outcomes. To help people feel in control the process, it’s crucial to provide clear and continuous feedback throughout." + }, + { + "type": "paragraph", + "text": "Display a drag image as soon as people drag a selection about three points. It works well to create a translucent representation of the content people are dragging. Translucency helps distinguish the representation from the original content and lets people see destinations as they pass over them. Display the drag image until people drop the content." + }, + { + "type": "paragraph", + "text": "If it adds clarity, modify the drag image to help people predict the result of a drag-and-drop operation. For example, when dragging a photo into a document, the drag image could expand to show the default size of the photo in the document. You can also use drag flocking to visually group multiple drag items — letting people confirm that they haven’t missed an item they want to drag — and then ungroup the items when people drop them. Although changing the drag image can provide valuable feedback, avoid creating a distracting experience in which the drag image is constantly and radically changing." + }, + { + "type": "paragraph", + "text": "Show people whether a destination can accept dragged content. For example, you might display an insertion point or highlight a containing view only when the destination can accept a dragged item, and show no visual feedback — or an explicit “not allowed” image, like the circle.slash from SF Symbols — when it can’t. Display highlighting or other visual cues only while the content is positioned above the destination, removing the visual feedback when people drag the content away. When there are multiple possible destinations, provide visual cues that help people identify one at a time." + }, + { + "type": "paragraph", + "text": "When people drop an item on an invalid destination, or when dropping fails, provide visual feedback. For example, the item can move back from its current location to its source (if the source is still visible) or it can scale up and fade out to give the impression of the item evaporating instead of landing successfully." + } + ] + }, + { + "heading": "Accepting drops", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Scroll the contents of a destination when necessary. When people drag an item within a scrolling container that has a lot of content, the content can automatically scroll as people move the item over it. This behavior makes it easy for people to find the right place to drop the item, but if they continue the drag operation outside of the container, automatic scrolling is no longer necessary. System-provided text views and text fields behave this way by default." + }, + { + "type": "paragraph", + "text": "When there’s a choice, pick the richest version of dropped content your app can accept. For example, if people drag a chart object from another app, the drag operation might offer both the rich, native chart object and a simple image of it. If your app supports charts, extract and display the native chart object; it it doesn’t, use the image instead." + }, + { + "type": "paragraph", + "text": "Extract only the relevant portion of dropped content if necessary. For example, when people drag a contact to a recipient field in an email, Mail displays only the name and email address, not the contact’s address information." + }, + { + "type": "paragraph", + "text": "When a physical keyboard is attached, check for the Option key at drop time. When people hold the Option key while dragging, they can force a drag-and-drop operation within the same container to behave like a copy. If people stop holding Option before dropping content in the same container, the drag operation results in a move." + }, + { + "type": "paragraph", + "text": "Provide feedback when dropped content needs time to transfer. For example, you might display a progress indicator to help people estimate how long the transfer will take. In collections, lists, and tables, you might also display a placeholder at the drop location so people know where to find the content after it finishes transferring. The system can display an alert when a time-consuming transfer occurs between apps." + }, + { + "type": "paragraph", + "text": "Provide feedback when dropped content initiates a task or action. If people drop content onto a control that initiates a task — such as printing — show people that the task has begun and keep them informed of its progress." + }, + { + "type": "paragraph", + "text": "Apply appropriate styling to dropped text. When the source and destination both support the same text styles, make sure dropped text maintains its original font, typeface, size, and other attributes. Otherwise, apply the destination’s style to dropped text." + }, + { + "type": "paragraph", + "text": "After a drop, maintain the content’s selection state in the destination, updating it in the source as needed. People expect the content they drop to remain selected so they can immediately act on it. When the source and destination are the same container, the content disappears from its original location when the drag operation performs a move. When a drag operation within the same container performs a copy, remove the selection state from the content that remains in the original location. When people drag selected content to a different container, deselect the content in the source." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Let people perform multiple simultaneous drag activities. In iPadOS, people can sequentially add items to an in-progress drag session, gathering as many items as their fingers can handle. For example, people can select an app icon on the Home Screen, start dragging it, and select additional app icons before dropping all of them in a different Home Screen or in a folder. To support this interaction, you need to let people add items during a drag — providing visual feedback through flocking — and accept multiple, simultaneous drops." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider letting people drag content from your app into the Finder. When you support this, be sure to present the content in a format your app can open later. For example, Calendar lets people drag an event to the Finder as a .ics file. People can share this file with others or drag it back to Calendar to open it. When necessary, you can output dragged content in a clipping, which is a temporary container for storing dragged content. For example, most system apps let people drag text to the Finder, where it appears as a clipping. Later, people can drag the clipping into a text field or other location that accepts text. Note that a drag-and-drop clipping isn’t related to the Clipboard." + }, + { + "type": "paragraph", + "text": "Let people drag selected content from an inactive window without first making the window active. Selected content in an inactive window is known as a background selection and has a different appearance from selected content in the active window. In general, people expect to drag a background selection to the active window without bringing the inactive window forward." + }, + { + "type": "paragraph", + "text": "When possible, let people drag individual items from an inactive window without affecting an existing background selection. For example, people can drag an unselected file from an inactive Finder window without deselecting any of the window’s selected files." + }, + { + "type": "paragraph", + "text": "Consider displaying a badge during multi-item drag operations. A badge is a small filled oval containing a number you can use to indicate the number of items people are dragging. If a destination can accept only a subset of dragged items, update the badge to show the new number." + }, + { + "type": "paragraph", + "text": "Consider changing the pointer appearance to indicate what will happen when people drop content. In addition to using the copy pointer, you might want to use the drag link, disappearing item, and operation not allowed pointers, depending on the situation. For guidance, see Pointers." + }, + { + "type": "paragraph", + "text": "As much as possible, let people select and drag content with a single motion. Unless people are selecting multiple items, they appreciate it when they don’t have to pause between making a selection and starting the drag operation." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When possible, launch your app to handle content that people drop into empty space. When you associate a user activity with draggable app content, your app can open a window or scene that handles the content when people drop it. For example, when people drop a URL into empty space, it launches Safari; when people drop Quick Look–supported content, Quick Look launches to display it. For developer guidance, see NSUserActivity." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Universal Control" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Drag and drop — UIKit" + }, + { + "type": "paragraph", + "text": "Drag and Drop — AppKit" + }, + { + "type": "paragraph", + "text": "File Provider" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "October 24, 2023", + "Added artwork." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/drag-and-drop#Best-practices" + }, + { + "title": "Providing feedback", + "url": "/design/human-interface-guidelines/drag-and-drop#Providing-feedback" + }, + { + "title": "Accepting drops", + "url": "/design/human-interface-guidelines/drag-and-drop#Accepting-drops" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/drag-and-drop#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/drag-and-drop#iOS-iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/drag-and-drop#macOS" + }, + { + "title": "Pointers", + "url": "/design/human-interface-guidelines/pointing-devices#Pointers" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/drag-and-drop#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/drag-and-drop#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/drag-and-drop#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/drag-and-drop#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/drag-and-drop#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/drag-and-drop#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Entering data", + "url": "https://developer.apple.com/design/human-interface-guidelines/entering-data", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Entering information can be a tedious process regardless of the interaction methods people use. Improve the experience by:" + }, + { + "type": "list", + "items": [ + "Pre-gathering as much information as possible to minimize the amount of data that people need to supply", + "Supporting all available input methods so people can choose the method that works for them" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Get information from the system whenever possible. Don’t ask people to enter information that you can gather automatically — such as from settings — or by getting their permission, such as their location or calendar information." + }, + { + "type": "paragraph", + "text": "Be clear about the data you need. For example, you might display a prompt in a text field — like “username@company.com” — or provide an introductory label that describes the information, like “Email.” You can also prefill fields with reasonable default values, which can minimize decision making and speed data entry." + }, + { + "type": "paragraph", + "text": "Use a secure text-entry field when appropriate. If your app or game needs sensitive data, use a field that obscures people’s input as they enter it, typically by displaying a small filled circle symbol for each character. For developer guidance, see SecureField. In tvOS, you can also configure a digit entry view to obscure the numerals people enter (for developer guidance, see isSecureDigitEntry). When you use the system-provided text field in visionOS, the system shows the entered data to the wearer, but not to anyone else; for example, a secure text field automatically blurs when people use AirPlay to stream their content." + }, + { + "type": "paragraph", + "text": "Never prepopulate a password field. Always ask people to enter their password or use biometric or keychain authentication. For guidance, see Managing accounts." + }, + { + "type": "paragraph", + "text": "When possible, offer choices instead of requiring text entry. It’s usually easier and more efficient to choose from lists of options than to type information, even when a keyboard is conveniently available. When it makes sense, consider using a picker, menu, or other selection component to give people an easy way to provide the information you need." + }, + { + "type": "paragraph", + "text": "As much as possible, let people provide data by dragging and dropping it or by pasting it. Supporting these interactions can ease data entry and make your experience feel more integrated with the rest of the system." + }, + { + "type": "paragraph", + "text": "Dynamically validate field values. People can get frustrated when they have to go back and correct mistakes after filling out a lengthy form. When you verify values as soon as people enter them — and provide feedback as soon as you detect a problem — you give them the opportunity to correct errors right away. For numeric data in particular, consider using a number formatter, which automatically configures a text field to accept only numeric values. You can also configure a formatter to display the value in a specific way, such as with a certain number of decimal places, as a percentage, or as currency." + }, + { + "type": "paragraph", + "text": "When data entry is necessary, make sure people understand that they must provide the required data before they can proceed. For example, if you include a Next or Continue button after a set of text fields, make the button available only after people enter the data you require." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider using an expansion tooltip to show the full version of clipped or truncated text in a field. An expansion tooltip behaves like a regular tooltip, appearing when the pointer rests on top of a field. Apps running in macOS — including iOS and iPadOS apps running on a Mac — can use an expansion tooltip to help people view the complete data they entered when a text field is too small to display it. For guidance, see Offering help > macOS, visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Text fields" + }, + { + "type": "paragraph", + "text": "Virtual keyboards" + }, + { + "type": "paragraph", + "text": "Keyboards" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Input events — SwiftUI" + } + ] + }, + { + "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/entering-data#Best-practices" + }, + { + "title": "digit entry view", + "url": "https://developer.apple.com/design/human-interface-guidelines/digit-entry-views" + }, + { + "title": "Managing accounts", + "url": "/design/human-interface-guidelines/managing-accounts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/entering-data#Platform-considerations" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/entering-data#macOS" + }, + { + "title": "Offering help > macOS, visionOS", + "url": "https://developer.apple.com/design/human-interface-guidelines/offering-help#macOS-visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/entering-data#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/entering-data#Related" + }, + { + "title": "Text fields", + "url": "/design/human-interface-guidelines/text-fields" + }, + { + "title": "Virtual keyboards", + "url": "/design/human-interface-guidelines/virtual-keyboards" + }, + { + "title": "Keyboards", + "url": "/design/human-interface-guidelines/keyboards" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/entering-data#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/entering-data#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/entering-data#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Feedback", + "url": "https://developer.apple.com/design/human-interface-guidelines/feedback", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Providing clear, consistent feedback as people interact with your app or game can make it feel intuitive and encourage deeper exploration. Feedback can communicate several different things, such as:" + }, + { + "type": "list", + "items": [ + "The current status of something", + "The success or failure of an important task or action", + "A warning about an action that can have negative consequences", + "An opportunity to correct a mistake or problematic situation" + ] + }, + { + "type": "paragraph", + "text": "The most effective feedback tends to match the significance of the information to the way it’s delivered. For example, it often works well to display status information in a passive way so that people can view it when they need it. In contrast, a warning about possible data loss needs to interrupt people so they have a chance to avoid the problem." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make sure all feedback is accessible. When you use multiple ways to provide feedback, you reach more people and give them the opportunity to receive the feedback in ways that work for them. For example, when you provide feedback using color, text, sound, and haptics, people can receive it whether they silence their device, look away from the screen, or use VoiceOver. (For guidance on providing haptic feedback, see Playing haptics.)" + }, + { + "type": "paragraph", + "text": "Consider integrating status feedback into your interface. When status feedback is available near the items it describes, people get important information without having to take action or leave their current context. For example, Mail in iOS and iPadOS describes the most recent update and displays the number of unread messages in the toolbar of the mailbox screen, making the information unobtrusive but easy for people to check when they’re interested." + }, + { + "type": "paragraph", + "text": "Use alerts to deliver critical — and ideally actionable — information. By design, alerts disrupt the current context, so you need to match the importance of the information to the level of interruption. Alerts can lose their impact if you use them too often or to deliver unimportant information. For guidance, see Alerts." + }, + { + "type": "paragraph", + "text": "Warn people when they initiate a task that can cause data loss that’s unexpected and irreversible. In contrast, don’t warn people when data loss is the expected result of their action. For example, the Finder doesn’t warn people every time they throw away a file because deleting the file is the expected result." + }, + { + "type": "paragraph", + "text": "When it makes sense, confirm that a significant action or task has completed. For example, people appreciate getting feedback that confirms a successful Apple Pay transaction. It’s generally best to reserve this type of confirmation for activities that are sufficiently important — because people typically expect their action or task to succeed, they only need to know when it doesn’t." + }, + { + "type": "paragraph", + "text": "Show people when a command can’t be carried out and help them understand why. For example, if people request directions without specifying a destination, Maps tells them that it can’t provide directions to and from the same location." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Avoid displaying an indeterminate progress indicator — such as a loading indicator — in a watchOS app. An animated indicator can make people think they need to continue paying attention to the display, which isn’t a good user experience. To provide a better experience, reassure people that they’ll receive a notification when the process completes." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Playing audio" + }, + { + "type": "paragraph", + "text": "Playing haptics" + }, + { + "type": "paragraph", + "text": "Motion" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Animation and haptics — UIKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/feedback#Best-practices" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Alerts", + "url": "/design/human-interface-guidelines/alerts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/feedback#Platform-considerations" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/feedback#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/feedback#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/feedback#Related" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Motion", + "url": "/design/human-interface-guidelines/motion" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/feedback#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/feedback#Videos" + } + ], + "image_count": 0 + }, + { + "title": "File management", + "url": "https://developer.apple.com/design/human-interface-guidelines/file-management", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Document-based apps — such as Pages, Keynote, Photos, and Preview — help people create, edit, and save documents and files, often providing customized ways for people to browse for content they want to open in the app." + }, + { + "type": "paragraph", + "text": "People also expect to browse documents without first opening a document-based app. On a Mac, for example, people use the Finder to access the macOS file system; on iPhone, iPad, and Apple Vision Pro, people use the Files app to manage the documents and files on their device. In watchOS and tvOS, people don’t typically create, edit, or manage documents, so these systems don’t provide a document-browsing interface." + } + ] + }, + { + "heading": "Creating and opening files", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use app menus and keyboard shortcuts to give people convenient ways to create and open documents. In iPadOS and macOS, people expect to create new documents or open existing ones using familiar menu commands. When you provide commands like New or Open, iPadOS presents them in the shortcuts interface that displays when people hold the Command key on a connected hardware keyboard, and macOS presents them in the menu bar File menu. Regardless of the availability of keyboard shortcuts, include an Add (+) button to help people create a new document. In a macOS app, you put the add action in the File menu (for guidance, see File menu)." + }, + { + "type": "paragraph", + "text": "If your app requires a custom file browser, support people’s understanding of the platform’s file system. People who are familiar with the Finder and Files apps already understand the basic layout of their device’s file system. Although you might want to show the most relevant part of the file system when your custom file browser opens — for example, a Documents or iCloud folder or the most recently selected location — let people use your browser to view the rest of the file system if they want." + } + ] + }, + { + "heading": "Saving work", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Help people be confident that their work is always preserved unless they cancel or delete it. In general, avoid making people take an explicit action to save their work. Instead, automatically perform periodic saves while they’re editing and when they close a file or switch to another app." + }, + { + "type": "paragraph", + "text": "Hide file extensions by default, but let people view them if they choose. Be sure to reflect the current choice in all the save or open interfaces you display." + } + ] + }, + { + "heading": "Quick Look previews", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Quick Look helps you create previews of the files your app handles so that people can view them within your app and in some cases interact with them. For example, you can use Quick Look to let people listen to a preview of an audio file, add markup to a photo’s preview, or rotate and scale a 3D file preview to examine it in different ways." + }, + { + "type": "paragraph", + "text": "Use a Quick Look viewer to let people preview a file even when your app can’t open it. If your app lets people attach or otherwise interact with files that it doesn’t support, implementing a Quick Look viewer lets people preview those files without leaving your app." + }, + { + "type": "paragraph", + "text": "Consider implementing a Quick Look generator if your app produces custom file types. A Quick Look generator lets other apps — including the Finder, Files, and Spotlight — display previews of your documents, making it easier for people to find them." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Document launcher", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Starting in iOS 18 and iPadOS 18, document-based apps can use the system’s document launcher to give people a consistent, highly graphical way to browse, open, and create files. The document launcher presents a full-screen experience that highlights key elements of your app’s theme, while making it easy for people to create new documents. For developer guidance, see DocumentGroupLaunchScene." + }, + { + "type": "paragraph", + "text": "The document launcher consists of three main parts:" + }, + { + "type": "list", + "items": [ + "A title card that displays the app title and two app-specific buttons", + "A background image that appears behind the title card and additional images — called accessories — that can appear around it", + "A sheet that contains a file browser and optional app-specific controls" + ] + }, + { + "type": "paragraph", + "text": "You can customize all three parts of the document launcher. Although the system automatically displays your app name in the title card, you specify the text and functions of the card’s primary and secondary buttons. You can also create a custom background image, one or more accessory images to surround the title card, and provide some custom controls that can appear in the file browser’s toolbar." + }, + { + "type": "paragraph", + "text": "Assign the title card’s buttons to your app’s most important functions. The primary button typically creates a new document, and the secondary button can provide additional options. For example, the primary button in Numbers is Start Writing and the secondary button is Choose a Template." + }, + { + "type": "paragraph", + "text": "Provide a background that’s clearly distinct from the accessories and title card. You can use a solid color, a gradient, or a pattern. Avoid including complex images or patterns that might distract from foreground elements." + }, + { + "type": "paragraph", + "text": "Be mindful of accessory placement. For example, you can place accessories both in front of and behind the title card to create the appearance of depth, but you need to make sure that your app name and both buttons remain clearly visible. Avoid cluttering the title card with too many accessories, and be sure to test its overall appearance across the range of screen sizes and device orientations that you support." + }, + { + "type": "paragraph", + "text": "Use animation sparingly. Too much motion on the display can confuse or disorient people. If you want to animate your accessories, consider creating gentle, repeating animations that subtly highlight and enhance your app’s content. For example, you might create an animation that makes an accessory appear to breathe or sway softly. For guidance, see Motion." + } + ] + }, + { + "heading": "File provider app extension", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "If your app can share its files with other apps, you can create a file provider app extension that displays a custom interface for importing, exporting, opening, and moving your app’s documents. For developer guidance, see File Provider. An app extension is code you provide that people can install and use to extend the functionality of a specific area of the system; to learn more, see App extensions." + }, + { + "type": "paragraph", + "text": "When someone uses your file provider extension to open or import documents, display only documents that are appropriate in the current context. For example, if a PDF-editing app loads your extension, only list PDF files for opening or import. You might also want to display additional information, such as modification dates, sizes, and whether documents are local or remote." + }, + { + "type": "paragraph", + "text": "Let people select a destination when exporting and moving documents. Unless your app stores documents in a single directory, let people navigate to a specific destination in your directory hierarchy. You could also provide a way to add new subdirectories." + }, + { + "type": "paragraph", + "text": "Avoid including a custom top toolbar. Your extension loads within a modal view that already includes a toolbar. Providing a second toolbar is confusing and takes space away from your content." + }, + { + "type": "paragraph", + "text": "Your app can also let people browse and open files from other apps. For developer guidance, see Adding a document browser to your app." + } + ] + }, + { + "heading": "Custom file management", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "People have strong associations with the familiar file browsing experience of the Finder and most document-based apps. Use the default file browser unless you have an important reason to create a custom one." + }, + { + "type": "paragraph", + "text": "Make your custom file-opening interface convenient. For example, people might appreciate an “open recent” action in addition to the simple “open” action. You might also want to let people choose criteria on which to filter the file-browsing experience, or select multiple documents to open at once. In a macOS open panel, you can customize the title of the Open button to reflect the task — for example, if your app lets people insert a file’s contents into the current document, you might change the title to Insert." + }, + { + "type": "paragraph", + "text": "Provide a save interface to let people change a file’s name, format, or location. By default, a new document’s title is “Untitled” until people choose a custom name. As with a document-opening interface, a save view can also provide a browsing experience that defaults to a logical location to help people place the saved document where they want. If you support saving content in different formats, also give people a way to choose a specific file format." + }, + { + "type": "paragraph", + "text": "Consider extending the functionality of the Save dialog. If it makes sense in your app, you can add a custom accessory view containing useful settings or options to the Save dialog. For example, the dialog for saving Mail messages as files contains an option to include attachments." + } + ] + }, + { + "heading": "Finder Sync extensions", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "If your app syncs local and remote files, you can create a Finder Sync app extension to express file synchronization status and control within the Finder. For developer guidance, see Finder Sync." + }, + { + "type": "paragraph", + "text": "For example, you can use a Finder Sync extension to:" + }, + { + "type": "list", + "items": [ + "Display badges in the Finder to indicate the sync status of items", + "Provide custom contextual menu items that perform file and folder management tasks, like favoriting and adding password-protection", + "Provide custom toolbar buttons that perform global actions, like initiating a sync operation" + ] + }, + { + "type": "paragraph", + "text": "Help people avoid losing work if they turn off autosaving. People can turn off autosaving by selecting the “Ask to keep changes when closing documents” toggle in Desktop & Dock settings. In this scenario, show that a document has unsaved changes and present a save dialog when people choose to close the document, quit your app, log out, or restart." + }, + { + "type": "paragraph", + "text": "When autosaving is off, make sure people know when a document has unsaved changes. To show that there are unsaved changes, display a dot on the document window’s close button and next to the document’s name in your app’s Window menu. When autosaving is on, showing a dot in these locations is confusing, because it implies that people need to take action to avoid losing their work. Regardless of autosave status, you can append “Edited” to the document’s title in the title bar, but be sure to remove this suffix as soon as autosave occurs or when people explicitly save their work." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Toolbars" + }, + { + "type": "paragraph", + "text": "File menu" + }, + { + "type": "paragraph", + "text": "Printing" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Documents — SwiftUI" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 10, 2024", + "Added guidelines for using the document launcher in iOS and iPadOS." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Creating and opening files", + "url": "/design/human-interface-guidelines/file-management#Creating-and-opening-files" + }, + { + "title": "File menu", + "url": "/design/human-interface-guidelines/the-menu-bar#File-menu" + }, + { + "title": "Saving work", + "url": "/design/human-interface-guidelines/file-management#Saving-work" + }, + { + "title": "Quick Look previews", + "url": "/design/human-interface-guidelines/file-management#Quick-Look-previews" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/file-management#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/file-management#iOS-iPadOS" + }, + { + "title": "Document launcher", + "url": "/design/human-interface-guidelines/file-management#Document-launcher" + }, + { + "title": "Motion", + "url": "/design/human-interface-guidelines/motion" + }, + { + "title": "File provider app extension", + "url": "/design/human-interface-guidelines/file-management#File-provider-app-extension" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/file-management#macOS" + }, + { + "title": "Custom file management", + "url": "/design/human-interface-guidelines/file-management#Custom-file-management" + }, + { + "title": "Finder Sync extensions", + "url": "/design/human-interface-guidelines/file-management#Finder-Sync-extensions" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/file-management#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/file-management#Related" + }, + { + "title": "Toolbars", + "url": "/design/human-interface-guidelines/toolbars" + }, + { + "title": "Printing", + "url": "/design/human-interface-guidelines/printing" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/file-management#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/file-management#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/file-management#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Going full screen", + "url": "https://developer.apple.com/design/human-interface-guidelines/going-full-screen", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apple TV and Apple Watch don’t offer full-screen modes because apps and games already fill the screen by default. Apple Vision Pro doesn’t offer a full-screen mode because people can expand a window to fill more of their view or use the Digital Crown to hide passthrough and transition to a more immersive experience (for guidance, see Immersive experiences)." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Support full-screen mode when it makes sense for your experience. People appreciate full-screen mode when they want to concentrate on a task or be immersed in content. Consider offering a full-screen mode if your experience lets people play a game; view media like videos or photo slideshows; or perform an in-depth task that benefits from a distraction-free environment." + }, + { + "type": "paragraph", + "text": "If necessary, adjust your layout in full-screen mode, but don’t programmatically resize your window. When a window is larger in full-screen mode than in non-full-screen mode, you want to keep essential content prominent while making good use of the extra space. For example, it might make sense to adjust the proportions of your interface without changing which items appear. If you make such adjustments, be sure they’re subtle enough to maintain a consistent interface and avoid causing visually jarring transitions between modes." + }, + { + "type": "paragraph", + "text": "Continue to provide access to essential features and controls so people can complete their task without exiting full-screen mode. For example, a full-screen media experience needs to make playback controls persistently available or easy to reveal when people need them." + }, + { + "type": "paragraph", + "text": "Except in games, let people reveal the Dock while your iPadOS or macOS app is in full-screen mode. In iPadOS and macOS, it’s important to preserve access to the Dock so people can quickly open other apps and Dock items. To help prevent people from accidentally revealing the Dock while they’re playing your full-screen game, you can ask iPadOS to ignore an initial swipe up from the screen’s bottom edge or hide the Dock entirely in macOS. For developer guidance, see preferredScreenEdgesDeferringSystemGestures (SwiftUI), preferredScreenEdgesDeferringSystemGestures (UIKit) and hideDock (AppKit)." + }, + { + "type": "paragraph", + "text": "After people switch away from your full-screen experience, help them resume where they left off when they return. For example, a game or a slideshow needs to pause automatically when people leave the experience so they don’t miss anything." + }, + { + "type": "paragraph", + "text": "Let people choose when to exit full-screen mode. People generally don’t expect full-screen mode to end automatically when they switch to a different experience or finish an absorbing activity, like playing a game or viewing a movie." + }, + { + "type": "paragraph", + "text": "Prioritize content by temporarily hiding toolbars and navigation controls. You can offer a distraction-free environment by hiding elements when content is the primary focus, such as when viewing full-screen photos or reading a document. If you implement such behavior, let people restore the hidden elements with a familiar gesture or action like tapping, swiping down, or moving the cursor to the top of the screen. Be sure to keep controls visible when they’re essential for navigation or performing tasks. Although a visionOS window can hide its toolbars or navigation controls, people generally expect different types of immersive experiences while wearing Apple Vision Pro; for guidance, see Immersive experiences." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider deferring system gestures to prevent accidental exits in a full-screen app or game. By default, the Home Screen indicator automatically hides shortly after someone switches to your app or game. It reappears when someone interacts with the bottom portion of the screen, allowing them to swipe once to exit. Whenever possible, retain this behavior because it’s familiar and what people expect. If supporting this results in unexpected exits, you can enable two swipes rather than one to exit. For developer guidance, see preferredScreenEdgesDeferringSystemGestures." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use the system-provided full-screen experience. Using the system’s full-screen support ensures that your full-screen window works well in all contexts. For example, some Mac models include a camera housing that occupies an area at the top-center of the screen. Using the system’s full-screen support automatically accommodates this area. For developer guidance, see toggleFullScreen(_:)." + }, + { + "type": "paragraph", + "text": "In a game, don’t change the display mode when players go full screen. People expect to be in control of their display mode, and changing it automatically doesn’t improve performance." + }, + { + "type": "paragraph", + "text": "For additional developer guidance, see Managing your game window for Metal in macOS." + }, + { + "type": "paragraph", + "text": "Always let people choose when to enter full-screen mode. Prefer letting people use your window’s Enter Full Screen button, View menu item, or the Control-Command-F keyboard shortcut. Avoid offering a custom menu of window modes. In a game, you might also provide a custom toggle that turns full-screen mode on and off." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Layout" + }, + { + "type": "paragraph", + "text": "Multitasking" + }, + { + "type": "paragraph", + "text": "Windows" + }, + { + "type": "paragraph", + "text": "The menu bar" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "fullScreenCover(item:onDismiss:content:) — SwiftUI" + }, + { + "type": "paragraph", + "text": "NSScreen — AppKit" + }, + { + "type": "paragraph", + "text": "NSWindow.CollectionBehavior — AppKit" + }, + { + "type": "paragraph", + "text": "Managing your game window for Metal in macOS — Swift, Objective-C" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated guidance for hiding toolbars and navigation controls, and deferring Home Screen indicator gestures in full-screen iOS and iPadOS apps and games." + ], + [ + "June 10, 2024", + "Enhanced guidance for playing a game in full-screen mode." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/going-full-screen#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/going-full-screen#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/going-full-screen#iOS-iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/going-full-screen#macOS" + }, + { + "title": "toggle", + "url": "https://developer.apple.com/design/human-interface-guidelines/toggles" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/going-full-screen#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/going-full-screen#Related" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "Multitasking", + "url": "/design/human-interface-guidelines/multitasking" + }, + { + "title": "Windows", + "url": "/design/human-interface-guidelines/windows" + }, + { + "title": "The menu bar", + "url": "/design/human-interface-guidelines/the-menu-bar" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/going-full-screen#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/going-full-screen#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/going-full-screen#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Launching", + "url": "https://developer.apple.com/design/human-interface-guidelines/launching", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Launching begins when someone opens your app or game, includes an initial download, and ends when the first screen is ready. After launching completes, you might offer an onboarding experience, which can give people a high-level view of your app or game." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Launch instantly. People want to start interacting with your app or game right away, and sometimes they don’t want to wait more than a couple of seconds." + }, + { + "type": "paragraph", + "text": "If the platform requires it, provide a launch screen. In iOS, iPadOS, and tvOS, the system displays your launch screen the moment your app or game starts and quickly replaces it with your first screen, giving people the impression that your experience is fast and responsive. For guidance, see Launch screens. macOS, visionOS, and watchOS don’t require launch screens." + }, + { + "type": "paragraph", + "text": "If you need a splash screen, consider displaying it at the beginning of your onboarding flow. A splash screen is a beautiful graphic that succinctly communicates branding and other information you need to provide. If you don’t provide an onboarding experience, you might display your splash screen as soon as launching completes." + }, + { + "type": "paragraph", + "text": "Restore the previous state when your app restarts so people can continue where they left off. Avoid making people retrace steps to reach their previous location in your app or game. Restore granular details of the previous state as much as possible. For example, scroll the view to people’s most recent position, and display windows in the same state and location in which people left them." + } + ] + }, + { + "heading": "Launch screens", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not applicable for macOS, visionOS, or watchOS." + }, + { + "type": "paragraph", + "text": "Downplay the launch experience. A launch screen isn’t part of an onboarding experience or a splash screen, and it isn’t an opportunity for artistic expression. A launch screen’s sole function is to enhance the perception of your experience as quick to launch and immediately ready to use." + }, + { + "type": "paragraph", + "text": "Design a launch screen that’s nearly identical to the first screen of your app or game. If you include elements that look different when launching completes, people may experience an unpleasant flash between the launch screen and your first screen. If your app or game displays a solid color before transitioning to the first screen, create a launch screen that displays only that solid color. Also make sure that your launch screen matches the device’s current orientation and appearance mode." + }, + { + "type": "paragraph", + "text": "Avoid including text on your launch screen, even if your first screen displays text. Because the content in a launch screen doesn’t change, any text you display won’t be localized." + }, + { + "type": "paragraph", + "text": "Don’t advertise. The launch screen isn’t a branding opportunity. Avoid creating a screen that looks like a splash screen or an “About” window, and don’t include logos or other branding elements unless they’re a fixed part of your app’s first screen." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for macOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Launch in the appropriate orientation. If your app or game supports both portrait and landscape modes, launch using the device’s current orientation. If your interface only runs in one orientation, launch in that orientation and let people rotate the device if necessary. Ensure a landscape-only interface responds correctly, regardless of whether people enter landscape orientation by rotating the device left or right. For guidance, see Layout." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "note", + "text": "NoteUnlike the layered images throughout much of a tvOS app, the launch screen is static." + }, + { + "type": "paragraph", + "text": "In a live-viewing app, consider automatically starting playback soon after people start the app. People come to your app to watch TV, so you might want to start playing new or recently viewed live content after a few seconds of inactivity. For guidance, see Live-viewing apps." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Consider launching in the Shared Space even if your app is fully immersive. Opening a window in the Shared Space lets you provide more context about your app or game while giving it time to load, and it also lets you present a control that people can use to open your fully immersive experience. In general, people appreciate being able to choose when to transition to a Full Space, especially if they’re currently running other apps in the Shared Space. For guidance, see Immersive experiences." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Onboarding" + }, + { + "type": "paragraph", + "text": "Loading" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Specifying your app’s launch screen — Xcode" + }, + { + "type": "paragraph", + "text": "Responding to the launch of your app — UIKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 10, 2024", + "Added guidance on displaying a splash screen." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/launching#Best-practices" + }, + { + "title": "Launch screens", + "url": "/design/human-interface-guidelines/launching#Launch-screens" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/launching#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/launching#iOS-iPadOS" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/launching#tvOS" + }, + { + "title": "layered images", + "url": "/design/human-interface-guidelines/images#Layered-images" + }, + { + "title": "Live-viewing apps", + "url": "/design/human-interface-guidelines/live-viewing-apps" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/launching#visionOS" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/launching#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/launching#Related" + }, + { + "title": "Loading", + "url": "/design/human-interface-guidelines/loading" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/launching#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/launching#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/launching#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Live-viewing apps", + "url": "https://developer.apple.com/design/human-interface-guidelines/live-viewing-apps", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Live-viewing apps need to elevate and prioritize live content. In every screen, draw people’s attention to live content and make sure they can distinguish it from video-on-demand (VOD) content at a glance." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Feature live content prominently and make it easy to access. People come to your app to watch content, so you want to minimize the interval between starting your app and playing content. When live content is in the first tab, people don’t have to tap more than once to start viewing it." + }, + { + "type": "paragraph", + "text": "Let people tap once — or not at all — to start playback. For example, you might display a Watch Now button on top of featured or recently viewed live content. When people tap this button, it immediately disappears and playback begins, replacing your app’s UI with a full-screen, immersive viewing experience." + }, + { + "type": "paragraph", + "text": "Make sure live content looks live. People need to be able to distinguish live content from VOD content. Although simply playing live content is the best way to make it feel live, you can also help people recognize live content by marking it in some way. For example, you might display other channels in a collection row titled “Live” and give each item a visual indicator — such as a badge, symbol, or sash — that identifies it as live." + }, + { + "type": "paragraph", + "text": "Consider indicating the progress of currently playing live content. People appreciate knowing where they’ll land when they jump into in-progress live content. You can use a progress bar or other indicator to show people how much content remains." + }, + { + "type": "paragraph", + "text": "Give people additional actions and viewing alternatives. In addition to playback, which always needs to be the primary action, make it easy for people to record, restart, download, and perform other actions that you support. Display these actions in the same order throughout your app — for example, Watch, Start Over, Record, and Favorite. Also, if the currently playing content is playing again at other times, show this information so that people can schedule their viewing." + }, + { + "type": "paragraph", + "text": "Consider using a content footer for browsing channels during playback. A content footer lets people browse without taking them out of the live playback experience. If you decide to use a content footer, be sure to:" + }, + { + "type": "list", + "items": [ + "Give it a subtle treatment, such as a darkening, to keep text legible and help all items remain visually distinct from the content playing behind it.", + "Make it easy for people to identify the thumbnail that represents the currently playing content by, for example, badging the thumbnail or tinting its progress bar.", + "Match the categories in the content footer to those in your electronic program guide (for related guidance, see EPG experience).", + "Design a simple, predictable way for people to invoke and dismiss the content footer — for example, if swiping up invokes the footer, people would expect swiping down to dismiss it." + ] + }, + { + "type": "paragraph", + "text": "Provide instant visual feedback when people change channels. This is essential for two reasons: people need confirmation that they’ve arrived at the channel they want, and providing feedback can give the streaming content some time to load." + }, + { + "type": "paragraph", + "text": "Match audio to the current context. When people start playing live content, they expect the audio to match even if they switch to browsing while the content plays in the background. However, when people navigate away from the live tab in your app, they leave the live-viewing context, so audio needs to stop." + } + ] + }, + { + "heading": "EPG experience", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Live-viewing apps typically provide an electronic program guide (EPG) that contains information about scheduled programming. Follow these guidelines to give people a streamlined EPG experience that feels designed specifically for your live-viewing app." + }, + { + "type": "paragraph", + "text": "Prominently display current information and make it easy to return to playback. When people first open the EPG, the current program, channel, and time needs to be easy to spot so they can instantly return to the current channel." + }, + { + "type": "paragraph", + "text": "Make browsing the EPG effortless. A typical EPG contains a lot of information, so it’s important to help people page, scroll, or jump through it easily. Also consider providing a My Channels group or a Favorites group that gives people quick access to the content they view most often." + }, + { + "type": "paragraph", + "text": "Group content into familiar categories to help people find it more easily. For example, you might use categories like Movies, TV Shows, Kids, Sports, and Popular. If your app includes a content footer, organize content thumbnails using the same categories as in the EPG." + }, + { + "type": "paragraph", + "text": "Let people browse the EPG without leaving their current content. For example, you can continue playing content in a picture-in-picture (PiP) mode or in the background while people browse the EPG." + } + ] + }, + { + "heading": "Cloud DVR", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If you support digital video recording (DVR) in the cloud, follow these guidelines to provide a great recording experience in your live-viewing app." + }, + { + "type": "paragraph", + "text": "Let people start and stop recording from the info panel. While live-streaming, people want to reveal the info panel to start recording immediately." + }, + { + "type": "paragraph", + "text": "Let people record a future program in a view that provides details about the content. Also, give people the option to record only that program or all future episodes." + }, + { + "type": "paragraph", + "text": "Help people adapt the recording experience to their needs. Let people specify precisely what they want to record, such as only the current episode, only new episodes, or only games that involve specific teams." + }, + { + "type": "paragraph", + "text": "Allow playback and other content-specific actions within your cloud DVR area. When people open a view that displays content details in your cloud DVR section, let them play or delete content and, if applicable, adjust recording settings." + }, + { + "type": "paragraph", + "text": "Consider offering a control that lets people manage cloud DVR settings. For example, you might let people delete recordings they’ve already watched or content that’s older than a certain number of days. Ideally, help people avoid running out of space by letting them set up automatic storage management, which overwrites the oldest or already viewed content." + } + ] + }, + { + "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": "Remotes" + }, + { + "type": "paragraph", + "text": "Playing video" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/live-viewing-apps#Best-practices" + }, + { + "title": "EPG experience", + "url": "/design/human-interface-guidelines/live-viewing-apps#EPG-experience" + }, + { + "title": "Cloud DVR", + "url": "/design/human-interface-guidelines/live-viewing-apps#Cloud-DVR" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/live-viewing-apps#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/live-viewing-apps#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/live-viewing-apps#Related" + }, + { + "title": "Remotes", + "url": "/design/human-interface-guidelines/remotes" + }, + { + "title": "Playing video", + "url": "/design/human-interface-guidelines/playing-video" + } + ], + "image_count": 0 + }, + { + "title": "Loading", + "url": "https://developer.apple.com/design/human-interface-guidelines/loading", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If your app or game loads assets, levels, or other content, design the behavior so it doesn’t disrupt or negatively impact the user experience." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Show something as soon as possible. If you make people wait for loading to complete before displaying anything, they can interpret the lack of content as a problem with your app or game. Instead, consider showing placeholder text, graphics, or animations as content loads, replacing these elements as content becomes available." + }, + { + "type": "paragraph", + "text": "Let people do other things in your app or game while they wait for content to load. Loading content in the background helps give people access to other actions. For example, a game could load content in the background while players learn about the next level or view an in-game menu. For developer guidance, see Improving the player experience for games with large downloads." + }, + { + "type": "paragraph", + "text": "If loading takes an unavoidably long time, give people something interesting to view while they wait. For example, you might provide gameplay hints, display tips, or introduce people to new features. Gauge the remaining loading time as accurately as possible to help you avoid giving people too little time to enjoy your placeholder content or having so much time that you need to repeat it." + }, + { + "type": "paragraph", + "text": "Improve installation and launch time by downloading large assets in the background. Consider using the Background Assets framework to schedule asset downloads — like game level packs, 3D character models, and textures — to occur immediately after installation, during updates, or at other nondisruptive times." + } + ] + }, + { + "heading": "Showing progress", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Clearly communicate that content is loading and how long it might take to complete. Ideally, content displays instantly, but for situations where loading takes more than a moment or two, you can use system-provided components — called progress indicators — to show that loading is ongoing. In general, you use a determinate progress indicator when you know how long loading will take, and you use an indeterminate progress indicator when you don’t. For guidance, see Progress indicators." + }, + { + "type": "paragraph", + "text": "For games, consider creating a custom loading view. Standard progress indicators work well in most apps, but can sometimes feel out of place in a game. Consider designing a more engaging experience by using custom animations and elements that match the style of your game." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "As much as possible, avoid showing a loading indicator in your watchOS experience. People expect quick interactions with their Apple Watch, so aim to display content immediately. In situations where content needs a second or two to load, it’s better to display a loading indicator than a blank screen." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Launching" + }, + { + "type": "paragraph", + "text": "Progress indicators" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Background Assets" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Revised guidance for storing downloads to reflect downloading large assets in the background." + ], + [ + "June 10, 2024", + "Added guidelines for showing progress and storing downloads, and enhanced guidance for games." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/loading#Best-practices" + }, + { + "title": "Showing progress", + "url": "/design/human-interface-guidelines/loading#Showing-progress" + }, + { + "title": "Progress indicators", + "url": "/design/human-interface-guidelines/progress-indicators" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/loading#Platform-considerations" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/loading#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/loading#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/loading#Related" + }, + { + "title": "Launching", + "url": "/design/human-interface-guidelines/launching" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/loading#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/loading#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/loading#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Managing accounts", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-accounts", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Ask people to create an account only if your core functionality requires it; otherwise, let people enjoy your app or game without one. If you require an account, consider using Sign in with Apple to give people a consistent sign-in experience they can trust and the convenience of not having to remember multiple accounts and authentication methods." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Explain the benefits of creating an account and how to sign up. If your app or game requires an account, write a brief, friendly description of the reasons for the requirement and its benefits. Display this message in your sign-in view." + }, + { + "type": "paragraph", + "text": "Delay sign-in for as long as possible. People often abandon apps when they’re forced to sign in before they can do anything useful. To help avoid this situation, give people a chance to get a sense of what your app or game does before asking them to make a commitment to it. For example, a shopping app might let people browse as much as they want, requiring sign-in only when they’re ready to make a purchase." + }, + { + "type": "paragraph", + "text": "If you don’t use Sign in with Apple in your iOS, iPadOS, macOS, or visionOS app, prefer using a passkey. Passkeys simplify account creation and authentication, eliminating the need for people to create or enter passwords. When an app supports passkeys, people simply provide their user name when creating a new account or signing in to an existing one. For developer guidance, see Supporting passkeys. 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)." + }, + { + "type": "paragraph", + "text": "Always identify the authentication method you offer. For example, if you display a button for signing in to your app with Face ID, title it using a phrase like “Sign In with Face ID” instead of a generic phrase like “Sign In.”" + }, + { + "type": "paragraph", + "text": "Refer only to authentication methods that are available in the current context. For example, don’t reference Face ID on a device that doesn’t offer it. Check the device’s capabilities and use the appropriate terminology. For developer guidance, see LABiometryType." + }, + { + "type": "paragraph", + "text": "In general, avoid offering an app-specific setting for opting in to biometric authentication. People turn on biometric authentication at the system level, so presenting an in-app setting is redundant and could be confusing." + }, + { + "type": "paragraph", + "text": "Avoid using the term passcode to refer to account authentication. People create a passcode to unlock their device or authenticate for Apple services. If you use the term in your interface, people might think you’re asking them to reuse their passcode in your app or game." + } + ] + }, + { + "heading": "Deleting accounts", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If you help people create an account within your app or game, you must also help them delete it, not just deactivate it. In addition to following the guidelines below, be sure to understand and comply with your region’s legal requirements related to account deletion and the right to be forgotten." + }, + { + "type": "important", + "text": "ImportantIf legal requirements compel your app to maintain accounts or information — such as digital health records — or to follow a specific account-deletion process, clearly describe the situation so people can understand the information or accounts you must maintain and the process you must follow." + }, + { + "type": "paragraph", + "text": "Provide a clear way to initiate account deletion within your app or game. If people can’t perform account deletion within your app, you must provide a direct link to the webpage on which people can do so. Make the link easy to discover — for example, don’t bury it in your Privacy Policy or Terms of Service pages." + }, + { + "type": "note", + "text": "Developer noteIf people used Sign in with Apple to create an account within your app, you revoke the associated tokens when they delete their account. See Token revocation." + }, + { + "type": "paragraph", + "text": "Provide a consistent account-deletion experience whether people perform it within your app or game or on the website. For example, avoid making one version of the deletion flow longer or more complicated than the other." + }, + { + "type": "paragraph", + "text": "Consider letting people schedule account deletion to occur in the future. People can appreciate the opportunity to use their remaining services or wait until their subscription auto-renews before deleting their account. If you offer a way to schedule account deletion, offer an option for immediate deletion as well." + }, + { + "type": "paragraph", + "text": "Tell people when account deletion will complete, and notify them when it’s finished. Because it can sometimes take a while to fully delete an account, it’s essential to keep people informed about the status of the deletion process so they know what to expect." + }, + { + "type": "paragraph", + "text": "If you support in-app purchases, help people understand how billing and cancellation work when they delete their account. For example, you might need to help people understand the following scenarios:" + }, + { + "type": "list", + "items": [ + "Billing for an auto-renewable subscription continues through Apple until people cancel the subscription, regardless of whether they delete their account.", + "After they delete their account, people need to cancel their subscription or request a refund." + ] + }, + { + "type": "paragraph", + "text": "In addition to helping people understand these scenarios, provide information that describes how to cancel subscriptions and manage purchases. For guidance, see Helping people manage their subscriptions and Providing help with in-app purchases." + }, + { + "type": "note", + "text": "NoteEven if people didn’t use your app to purchase the subscription, you still need to support account deletion." + } + ] + }, + { + "heading": "TV provider accounts", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Many popular TV providers let people sign in to their accounts at the system level, eliminating the need to authenticate on an app-by-app basis. If your TV provider app requires people to sign in, use TV Provider Authentication to provide the most efficient onboarding experience." + }, + { + "type": "paragraph", + "text": "Avoid displaying a sign-out option when people are signed in at the system level. If your app must include a sign-out option, invoking it needs to prompt people to navigate to Settings > TV Provider to sign out of their account." + }, + { + "type": "paragraph", + "text": "Never instruct people to sign out by adjusting privacy controls. The TV provider controls in Settings > Privacy aren’t a sign-out mechanism. These settings help people manage the apps that can access their TV provider account." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or visionOS." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Most people interact with Apple TV using a remote, not a keyboard, so ask for the minimum amount of information necessary." + }, + { + "type": "paragraph", + "text": "Prefer letting people use another device to sign up or authenticate. When you configure your app’s associated domains, Apple TV can work with other devices to safely suggest sign-in credentials, including Sign in with Apple. For developer guidance, see Configuring an associated domain." + }, + { + "type": "paragraph", + "text": "When people are signed in to a shared account, avoid asking them to choose their profile every time they become the current user. In tvOS 16 and later, your app can share its credentials with all users while storing each individual’s profile and user data separately. When you support this type of sharing, your app can automatically use the current user’s profile without asking each person to sign in separately to a shared account. For developer guidance, see kSecUseUserIndependentKeychain and User Management Entitlement." + }, + { + "type": "paragraph", + "text": "Minimize data entry. If you need to gather more than a small amount of information, ask people to visit a website from another device. If you need an email address, show the email keyboard screen, which includes a list of recently entered addresses." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use iCloud synchronization to provide access to the Keychain, letting people autofill user names and passwords and preserve app settings." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Onboarding" + }, + { + "type": "paragraph", + "text": "Sign in with Apple" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Supporting passkeys — Authentication Services" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Sign in with Apple", + "url": "/design/human-interface-guidelines/sign-in-with-apple" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/managing-accounts#Best-practices" + }, + { + "title": "Deleting accounts", + "url": "/design/human-interface-guidelines/managing-accounts#Deleting-accounts" + }, + { + "title": "Helping people manage their subscriptions", + "url": "/design/human-interface-guidelines/in-app-purchase#Helping-people-manage-their-subscriptions" + }, + { + "title": "Providing help with in-app purchases", + "url": "/design/human-interface-guidelines/in-app-purchase#Providing-help-with-in-app-purchases" + }, + { + "title": "TV provider accounts", + "url": "/design/human-interface-guidelines/managing-accounts#TV-provider-accounts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/managing-accounts#Platform-considerations" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/managing-accounts#tvOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/managing-accounts#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/managing-accounts#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/managing-accounts#Related" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/managing-accounts#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/managing-accounts#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Managing notifications", + "url": "https://developer.apple.com/design/human-interface-guidelines/managing-notifications", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You need to get permission before sending any notification. The system lets people change this decision in settings, where they can also silence all notifications (except for government alerts in some locales)." + } + ] + }, + { + "heading": "Integrating with Focus", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People appreciate receiving a notification for something they care about, but they don’t always appreciate being interrupted. To help people manage the experience, the system lets them specify delivery times and set up a Focus." + }, + { + "type": "list", + "items": [ + "A Focus helps people filter notifications during a time period they reserve for an activity like sleeping, working, reading, or driving.", + "Delivery scheduling lets people choose whether to receive notification alerts immediately or in a summary that’s delivered at times they choose." + ] + }, + { + "type": "paragraph", + "text": "People identify the contacts and apps that can break through a Focus to deliver notification alerts. In a Work Focus, for example, people might want to receive alerts from work colleagues, family members, and work-related apps as soon as notifications arrive. People might also want to receive all Time Sensitive notification alerts during a Focus. A Time Sensitive notification contains essential information people appreciate getting right away." + }, + { + "type": "important", + "text": "ImportantEven though a Focus might delay the delivery of a notification alert, the notification itself is available as soon as it arrives." + }, + { + "type": "paragraph", + "text": "To support these behavior customizations, you first identify the types of notifications your app or game can send. If you support direct communications — like phone calls and messages — you use communication notifications; for all other types of tasks, you use noncommunication notifications. To support communication notifications, you adopt SiriKit intents, which means people can use Siri to customize notification behaviors; for developer guidance, see INSendMessageIntent and UNNotificationContentProviding." + }, + { + "type": "paragraph", + "text": "You need to specify a system-defined interruption level for each noncommunication notification you send. The system uses the interruption level to help determine when to deliver the alert; when a communication notification arrives, the system uses the sender to determine when to deliver the alert." + }, + { + "type": "paragraph", + "text": "The system defines four interruption levels for noncommunication notifications:" + }, + { + "type": "list", + "items": [ + "Passive. Information people can view at their leisure, like a restaurant recommendation.", + "Active (the default). Information people might appreciate knowing about when it arrives, like a score update on their favorite sports team.", + "Time Sensitive. Information that directly impacts the person and requires their immediate attention, like an account security issue or a package delivery.", + "Critical. Urgent information about health and safety that directly impacts the person and demands their immediate attention. Critical notifications are extremely rare and typically come from governmental and public agencies or apps that help people manage their health or home." + ] + }, + { + "type": "paragraph", + "text": "Notification alerts in each system-defined interruption level can behave in the following ways:" + }, + { + "type": "table", + "rows": [ + [ + "Interruption level", + "Overrides scheduled delivery", + "Breaks through Focus", + "Overrides Ring/Silent switch on iPhone and iPad" + ], + [ + "Passive", + "No", + "No", + "No" + ], + [ + "Active", + "No", + "No", + "No" + ], + [ + "Time Sensitive", + "Yes", + "Yes", + "No" + ], + [ + "Critical", + "Yes", + "Yes", + "Yes" + ] + ] + }, + { + "type": "note", + "text": "NoteBecause a Critical notification can override the Ring/Silent switch and break through scheduled delivery and Focus, you must get an entitlement to send one." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Build trust by accurately representing the urgency of each notification. People have several ways to adjust how they receive your notifications — including turning off all notifications — so it’s essential to be as realistic as possible when assigning an interruption level. You don’t want people to feel that a notification uses a high level of urgency to interrupt them with low-priority information." + }, + { + "type": "paragraph", + "text": "Use the Time Sensitive interruption level only for notifications that are relevant in the moment. To help people understand the benefits of letting Time Sensitive notifications break through a Focus or scheduled delivery, make sure the notification is about an event that’s happening now or will happen within an hour. The first time a Time Sensitive notification arrives from your app, the system describes how such a notification works and gives people a way to turn it off if they don’t agree that the information requires their immediate attention. Going forward, the system periodically gives people additional opportunities to evaluate how your Time Sensitive notification is working for them. For developer guidance, see UNNotificationInterruptionLevel." + } + ] + }, + { + "heading": "Sending marketing notifications", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Don’t use notifications to send marketing or promotional content unless people explicitly agree to receive such information. When people want to learn about new features, content, or events related to your app or game, they can grant their permission to receive marketing notifications. For example, people who use a subscription app might appreciate getting an offer to become a subscriber, and game players might want to receive a special offer related to a live game event." + }, + { + "type": "paragraph", + "text": "Never use the Time Sensitive interruption level to send a marketing notification. People may have agreed to receive marketing notifications from your app, but such a notification must never break through a Focus or scheduled delivery setting." + }, + { + "type": "paragraph", + "text": "Get people’s permission if you want to send them promotional or marketing notifications. Before you send these notifications to people, you must receive their explicit permission to do so. Create an alert, modal view, or other interface that describes the types of information you want to send and gives people a clear way to opt in or out." + }, + { + "type": "paragraph", + "text": "Make sure people can manage their notification settings within your app. In addition to requesting permission to send informational or marketing notifications, you must also provide an in-app settings screen that lets people change their choice. For guidance, see Settings." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "By default, the notification settings people use for apps on their iPhone apply to the same apps on their Apple Watch. People can manage these settings in the Apple Watch app on iPhone, or they can access per-notification options — such as Mute 1 Hour or Turn off Time Sensitive — by swiping left when a notification arrives on their Apple Watch." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Privacy" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "User Notifications" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Integrating with Focus", + "url": "/design/human-interface-guidelines/managing-notifications#Integrating-with-Focus" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/managing-notifications#Best-practices" + }, + { + "title": "Sending marketing notifications", + "url": "/design/human-interface-guidelines/managing-notifications#Sending-marketing-notifications" + }, + { + "title": "Settings", + "url": "/design/human-interface-guidelines/settings" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/managing-notifications#Platform-considerations" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/managing-notifications#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/managing-notifications#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/managing-notifications#Related" + }, + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/privacy" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/managing-notifications#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/managing-notifications#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Modality", + "url": "https://developer.apple.com/design/human-interface-guidelines/modality", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Presenting content modally can:" + }, + { + "type": "list", + "items": [ + "Ensure that people receive critical information and, if necessary, act on it", + "Provide options that let people confirm or modify their most recent action", + "Help people perform a distinct, narrowly scoped task without losing track of their previous context", + "Give people an immersive experience or help them concentrate on a complex task" + ] + }, + { + "type": "paragraph", + "text": "Depending on the platform, you might use different components to present these types of modal experiences. For example, all platforms can present an alert, which is a modal view that delivers important information related to your app or game. In addition, each platform may define various types of modal views for presenting context-specific options, such as activity views, sheets, and confirmation dialogs or action sheets. To help people perform a distinct task, iOS, iPadOS, and macOS apps tend to use sheets or popovers, but iPadOS, macOS, and visionOS apps might also just use a separate window." + }, + { + "type": "paragraph", + "text": "To provide a temporary experience, like viewing media, or to help people perform a distinct, multistep task, like editing content, apps can offer a full-screen modal experience. In contrast, apps may also offer nonmodal types of full-screen experiences; for guidance, see Going full screen. visionOS apps can offer a range of immersive experiences; for guidance, see Immersive experiences." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Present content modally only when there’s a clear benefit. A modal experience takes people out of their current context and requires an action to dismiss, so it’s important to use modality only when it helps people focus or make choices that affect their content or device." + }, + { + "type": "paragraph", + "text": "Aim to keep modal tasks simple, short, and streamlined. If a modal task is too complicated, people can lose track of the task they suspended when they entered the modal view, especially if the modal view obscures their previous context." + }, + { + "type": "paragraph", + "text": "Take care to avoid creating a modal experience that feels like an app within your app. In particular, presenting a hierarchy of views within a modal task can make people forget how to retrace their steps. If a modal task must contain subviews, provide a single path through the hierarchy and avoid including buttons that people might mistake for the button that dismisses the modal view." + }, + { + "type": "paragraph", + "text": "Consider using a full-screen modal style for in-depth content or a complex task. A modal experience that fills a window or the device display minimizes distractions, so it can work well for presenting videos, photos, or camera views, or to support a multistep task like marking up a document or editing a photo. When a visionOS app runs alongside other apps in the Shared Space, a full-screen modal presentation fills a window; if people transition the app to a Full Space, the full-screen modal presentation can become a more immersive experience." + }, + { + "type": "paragraph", + "text": "Always give people an obvious way to dismiss a modal view. In general, it works well to follow the platform conventions people already know. For example, in iOS, iPadOS, and watchOS apps, people typically expect to find a button in the top toolbar or swipe down; in macOS and tvOS apps, people expect to find a button in the main content view." + }, + { + "type": "paragraph", + "text": "When necessary, help people avoid data loss by getting confirmation before closing a modal view. Regardless of whether people use a dismiss gesture or a button, if closing the view could result in the loss of user-generated content, be sure to explain the situation and give people ways to resolve it. For example, in iOS, you might present an action sheet that includes a save option." + }, + { + "type": "paragraph", + "text": "Make it easy to identify a modal view’s task. When people enter a modal view, they switch away from their previous context and might not return to it right away. When you provide a title that names the modal view’s task — or additional text that describes the task or provides guidance — you can help people keep their place in your app." + }, + { + "type": "paragraph", + "text": "Let people dismiss a modal view before presenting another one. Allowing multiple modal views to be visible at the same time tends to create visual clutter and can make your app seem scattered and disorganized. People need to remember the context they were in before a modal view appears, so presenting multiple views adds to people’s cognitive load, especially when a modal view hides another one by appearing on top of it. Although an alert can appear on top of all other content — including other modal views — you never want to display more than one alert at the same time." + } + ] + }, + { + "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": "Sheets" + }, + { + "type": "paragraph", + "text": "Alerts" + }, + { + "type": "paragraph", + "text": "Popovers" + }, + { + "type": "paragraph", + "text": "Action sheets" + }, + { + "type": "paragraph", + "text": "Activity views" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Presentation modifiers — SwiftUI" + }, + { + "type": "paragraph", + "text": "UIModalPresentationStyle — UIKit" + }, + { + "type": "paragraph", + "text": "Modal Windows and Panels — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Enhanced guidance for in-depth modal experiences and clarified guidance on multiple modal views." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Going full screen", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/modality#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/modality#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/modality#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/modality#Related" + }, + { + "title": "Sheets", + "url": "/design/human-interface-guidelines/sheets" + }, + { + "title": "Alerts", + "url": "/design/human-interface-guidelines/alerts" + }, + { + "title": "Popovers", + "url": "/design/human-interface-guidelines/popovers" + }, + { + "title": "Action sheets", + "url": "/design/human-interface-guidelines/action-sheets" + }, + { + "title": "Activity views", + "url": "/design/human-interface-guidelines/activity-views" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/modality#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/modality#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/modality#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Multitasking", + "url": "https://developer.apple.com/design/human-interface-guidelines/multitasking", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People expect to use multitasking on their devices, and they may think something is wrong if your app doesn’t allow it. With rare exceptions — such as some games, and Apple Vision Pro apps running in a Full Space — every app needs to work well with multitasking." + }, + { + "type": "paragraph", + "text": "In addition to app switching, multitasking can present different experiences on different devices; see Platform considerations." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A great multitasking experience helps people accomplish tasks in multiple apps by managing content in a variety of simultaneous contexts. Because you don’t know when people will initiate multitasking, your app or game always needs to be prepared to save and restore their context." + }, + { + "type": "paragraph", + "text": "Pause activities that require people’s attention or active participation when they switch away. If your app is a game or a media-viewing app, for example, make sure people don’t miss anything when they switch to another app. When they switch back, let them continue as if they never left." + }, + { + "type": "paragraph", + "text": "Respond smoothly to audio interruptions. Occasionally, audio from another app or the system itself may interrupt your app’s audio. For example, an incoming phone call or a music playlist initiated by Siri might interrupt your app’s audio. When situations like these occur, people expect your app to respond in the following ways:" + }, + { + "type": "list", + "items": [ + "Pause audio indefinitely for primary audio interruptions, such as playing music, podcasts, or audiobooks.", + "Temporarily lower the volume or pause the audio for shorter interruptions, such as GPS directional notifications, and resume the original volume or playback when the interruption ends." + ] + }, + { + "type": "paragraph", + "text": "For guidance, see Playing audio." + }, + { + "type": "paragraph", + "text": "Finish user-initiated tasks in the background. When someone starts a task like downloading assets or processing a video file, they expect it to finish even if they switch away from your app. If your app is in the middle of performing a task that doesn’t need additional input, complete it in the background before suspending." + }, + { + "type": "paragraph", + "text": "Use notifications sparingly. Your app can send notifications when it’s suspended or running in the background. If people start an important or time-sensitive task in your app, and then switch away from it, they might appreciate receiving a notification when the task completes so they can switch back to your app and take the next step. In contrast, people don’t generally need to know the moment a routine or secondary task completes. In this scenario, avoid sending an unnecessary notification; instead, let people check on the task when they return to your app. For guidance, see Managing notifications." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in watchOS." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On iPhone, multitasking lets people use FaceTime or watch a video in Picture in Picture while they also use a different app." + }, + { + "type": "paragraph", + "text": "The app switcher displays all currently open apps." + }, + { + "type": "paragraph", + "text": "A current FaceTime call can continue while people use another app." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On iPad, people can view and interact with the windows of several different apps at the same time. An individual app can also support multiple open windows, which lets people view and interact with more than one window in the same app at one time." + }, + { + "type": "paragraph", + "text": "People can use iPad with either full-screen or windowed apps. When full screen, apps occupy the full screen, and people can switch between individual app windows using the app switcher." + }, + { + "type": "paragraph", + "text": "When using windowed apps, app windows are resizable, and people can arrange them to suit their needs with behavior similar to macOS. The system provides window controls for common tiling configurations, entering full screen, minimizing, and closing windows. The system identifies the frontmost window by coloring its window controls and casting a drop shadow on windows behind it. For guidance, see Windows > iPadOS." + }, + { + "type": "paragraph", + "text": "Additionally, videos and FaceTime calls can also play in a Picture in Picture overlay above other content regardless of whether apps are full screen or windowed." + }, + { + "type": "note", + "text": "NoteApps don’t control multitasking configurations or receive any indication of the ones that people choose." + }, + { + "type": "paragraph", + "text": "To help your app respond correctly when people open it while windowed, make sure it adapts gracefully to different screen sizes. For guidance, see Layout and Windows; for developer guidance, see Multitasking on iPad, Mac, and Apple Vision Pro. To learn more about how people use iPad multitasking features, see Use multitasking on your iPad." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Mac, multitasking is the default experience because people typically run more than one app at a time, switching between windows and tasks as they work. When multiple app windows are open, macOS applies drop shadows that make the windows appear layered on the desktop, and applies other visual effects to help people distinguish different window states; for guidance, see macOS window states." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Apple TV, people can play or browse content while also playing movies or TV shows in Picture in Picture (where supported)." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Apple Vision Pro, people can run multiple apps at the same time in the Shared Space, viewing and switching between windows and volumes throughout the space." + }, + { + "type": "paragraph", + "text": "Only one window is active at a time in the Shared Space. When people look from one window to another, the window they’re currently looking at becomes active while the previous window becomes more translucent and appears to recede along the z-axis. Closing an app window in the Shared Space transitions the app to the background without quitting it." + }, + { + "type": "note", + "text": "NoteWhen an app is the Now Playing app, closing its window automatically pauses audio playback; if people want to resume playback, they can do so in Control Center without opening the window." + }, + { + "type": "paragraph", + "text": "Avoid interfering with the system-provided multitasking behavior. When people look from one window to another, visionOS applies a feathered mask to the window they look away from to clarify its changed state. To avoid interfering with this visual feedback, don’t change the appearance of a window’s edges." + }, + { + "type": "paragraph", + "text": "Don’t pause a window’s video playback when people look away from it. In visionOS, as in macOS, people expect the playback they start in one window to continue while they view or perform a task in another window." + }, + { + "type": "paragraph", + "text": "Be prepared for situations where your audio can duck. Unless an app is currently the Now Playing app, its audio can duck when people look away from it to another app." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Layout" + }, + { + "type": "paragraph", + "text": "Windows" + }, + { + "type": "paragraph", + "text": "Playing video" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Responding to the launch of your app — UIKit" + }, + { + "type": "paragraph", + "text": "Multitasking on iPad, Mac, and Apple Vision Pro — UIKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Reorganized guidance in platform considerations, and added guidance for multitasking with multiple windows in iPadOS." + ], + [ + "December 5, 2023", + "Added artwork for primary and auxiliary windows in iPadOS." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/multitasking#Platform-considerations" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/multitasking#Best-practices" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Managing notifications", + "url": "/design/human-interface-guidelines/managing-notifications" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/multitasking#iOS" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/multitasking#iPadOS" + }, + { + "title": "windows", + "url": "/design/human-interface-guidelines/windows" + }, + { + "title": "Windows > iPadOS", + "url": "/design/human-interface-guidelines/windows#iPadOS" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/multitasking#macOS" + }, + { + "title": "macOS window states", + "url": "/design/human-interface-guidelines/windows#macOS-window-states" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/multitasking#tvOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/multitasking#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/multitasking#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/multitasking#Related" + }, + { + "title": "Playing video", + "url": "/design/human-interface-guidelines/playing-video" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/multitasking#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/multitasking#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/multitasking#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Offering help", + "url": "https://developer.apple.com/design/human-interface-guidelines/offering-help", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let your app’s tasks inform the types of help people might need. For example, you might help people perform simple, one- or two-step tasks by displaying an inline view that succinctly describes the task. In contrast, if your app or game supports complex or multistep tasks you might want to provide a tutorial that teaches people how to accomplish larger goals. In general, directly relate the help you provide to the precise action or task people are doing right now and make it easy for people to dismiss or avoid the help if they don’t need it." + }, + { + "type": "paragraph", + "text": "Use relevant and consistent language and images in your help content. Always make sure guidance is appropriate for the current context. For example, if someone’s using the Siri Remote with your tvOS experience, don’t show tips or images that feature a game controller. Also be sure the terms and descriptions you use are consistent with the platform. For example, don’t write copy that tells people to click a button on an iPhone or tap a menu item on a Mac." + }, + { + "type": "paragraph", + "text": "Make sure all help content is inclusive. For guidance, see Inclusion." + }, + { + "type": "paragraph", + "text": "Avoid bloating your help content by explaining how standard components or patterns work. Instead, describe the specific action or task that a standard element performs in your app or game. If your experience introduces a unique control or expects people to use an input device in a nonstandard way — such as holding the Siri Remote rotated 90 degrees — orient people quickly, preferring animation or graphics to educate instead of a lengthy description." + } + ] + }, + { + "heading": "Creating tips", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A tip is a small, transient view that briefly describes how to use a feature in your app. Tips are a great way to teach people about new or less obvious features in your app, or help them discover faster ways to accomplish a task. For developer guidance, see TipKit." + }, + { + "type": "paragraph", + "text": "Use the most appropriate tip type for your app’s user interface. Display a popover tip when you want to preserve the content flow, or an inline tip when you want to ensure that surrounding information is visible. You can use an annotation-style inline tip when pointing to a specific UI element, or a hint-style tip when it’s not related to a specific piece of UI." + }, + { + "type": "paragraph", + "text": "Popover" + }, + { + "type": "paragraph", + "text": "Annotation" + }, + { + "type": "paragraph", + "text": "Hint" + }, + { + "type": "paragraph", + "text": "Use tips for simple features. Tips work best on features that are easy to describe and that people can complete with a few simple steps. If a feature requires more than three actions, it’s probably too complicated for a tip." + }, + { + "type": "paragraph", + "text": "Make tips short, actionable, and engaging. A tip’s goal is to encourage people to try new features. Use direct, action-oriented language to describe what the feature does and explain how to use it. Keep your tips to one or two sentences and avoid including content that’s promotional or related to a different feature or user flow. Promotional content is anything that advertises, sells, or isn’t aligned with the current context of what the person is doing." + }, + { + "type": "paragraph", + "text": "Define rules to help ensure your tips reach the intended audience. Not everyone benefits from every tip. For example, people who’ve already used a feature won’t appreciate viewing a tip that describes it. Use parameter-based or event-based eligibility rules to control when a tip appears, and only display a tip if someone might benefit from its use. When your app has more than one tip, set the display frequency so tips display at a reasonable cadence — for example, once every 24 hours." + }, + { + "type": "paragraph", + "text": "If there’s an image or symbol that people associate with the feature, consider including it in the tip, and prefer the filled variant. For example, a tip with a star can help people understand that the tip is related to favorites." + }, + { + "type": "paragraph", + "text": "If the feature is represented by an image that the tip connects to directly, avoid repeating the same image in both the tip and the UI." + }, + { + "type": "paragraph", + "text": "Use buttons to direct people to information or options. If your feature has settings people can customize, or you want to redirect people to an area where they can learn more about a feature, consider adding a button. Buttons can take people directly to the settings where they make adjustments. Or if there’s more information people might find useful, add a button to take them to additional resources, such as a setup flow." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, tvOS, or watchOS." + } + ] + }, + { + "heading": "macOS, visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A tooltip (called a help tag in user documentation) displays a small, transient view that briefly describes how to use a component in the interface. In apps that run on a Mac — including iPhone and iPad apps — tooltips can appear when a person holds the pointer over an element; in visionOS apps, a tooltip can appear when a person looks at an element or holds the pointer over it. For developer guidance, see help(_:)." + }, + { + "type": "paragraph", + "text": "Describe only the control that people indicate interest in. When people want to know how to use a specific control, they don’t want to learn how to use nearby controls or how to perform a larger task." + }, + { + "type": "paragraph", + "text": "Explain the action or task the control initiates. It often works well to begin the description with a verb — for example, “Restore default settings” or “Add or remove a language from the list.”" + }, + { + "type": "paragraph", + "text": "In general, avoid repeating a control’s name in its tooltip. Repeating the name takes up space in the tooltip and rarely adds value to the description." + }, + { + "type": "paragraph", + "text": "Be brief. As much as possible, limit tooltip content to a maximum of 60 to 75 characters (note that localization often changes the length of text). To make a description brief and direct, consider using a sentence fragment and omitting articles. If you need a lot of text to describe a control, consider simplifying your interface design." + }, + { + "type": "paragraph", + "text": "Use sentence case. Sentence case tends to appear more casual and approachable. If you write complete sentences, omit ending punctuation unless it’s required to be consistent with your app’s style." + }, + { + "type": "paragraph", + "text": "Consider offering context-sensitive tooltips. For example, you could provide different text for a control’s different states." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Onboarding" + }, + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Writing" + }, + { + "type": "paragraph", + "text": "Help menu" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "TipKit" + }, + { + "type": "paragraph", + "text": "NSHelpManager — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Included visionOS in guidance for creating tooltips." + ], + [ + "September 12, 2023", + "Added guidance for creating tips." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/offering-help#Best-practices" + }, + { + "title": "Inclusion", + "url": "/design/human-interface-guidelines/inclusion" + }, + { + "title": "Creating tips", + "url": "/design/human-interface-guidelines/offering-help#Creating-tips" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/offering-help#Platform-considerations" + }, + { + "title": "macOS, visionOS", + "url": "/design/human-interface-guidelines/offering-help#macOS-visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/offering-help#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/offering-help#Related" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Writing", + "url": "/design/human-interface-guidelines/writing" + }, + { + "title": "Help menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Help-menu" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/offering-help#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/offering-help#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/offering-help#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Onboarding", + "url": "https://developer.apple.com/design/human-interface-guidelines/onboarding", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Ideally, people can understand your app or game simply by experiencing it, but if onboarding is necessary, design a flow that’s fast, fun, and optional. When available, onboarding occurs after launching is complete — it isn’t part of the launch experience." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Teach through interactivity. People tend to grasp and retain information better when they can actually perform the task they’re learning about instead of just viewing instructional material. As much as possible, provide an interactive onboarding experience where people can safely test an action, discover a feature, or try out a game mechanic." + }, + { + "type": "paragraph", + "text": "Consider providing a collection of context-specific tips instead of a single onboarding flow. Integrating contextually relevant tips into your experience can help people learn about their current task while they make progress in your app or game. A context-specific tip can also help people learn better because it lets them concentrate on a single action or task before encountering new information. When you have instructional content that refers to a specific area of the interface, display these instructions near that area. For developer guidance, see TipKit." + }, + { + "type": "paragraph", + "text": "If you need to present a prerequisite onboarding flow, design a brief, enjoyable experience that doesn’t require people to memorize a lot of information. When onboarding is quick and entertaining, people are more likely to complete it. In contrast, if you try to teach too much, people can feel overwhelmed and may be less likely to remember what they learned." + }, + { + "type": "paragraph", + "text": "If it makes sense to offer a separate tutorial, consider making it optional. If you let people skip the tutorial when they first launch your app or game, don’t present it again on subsequent launches, but make sure it’s easy for people to find if they want to view it later. For example, you could make the tutorial available in a help, account, or settings area within your app or game." + }, + { + "type": "paragraph", + "text": "Keep onboarding content focused on the experience you provide. People enter your onboarding flow to learn about your app or game; they don’t need to learn how to use the system or the device." + } + ] + }, + { + "heading": "Additional content", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Briefly display a splash screen if necessary. If you need to include a splash screen, design a beautiful graphic that communicates succinctly. Aim to display your splash screen just long enough for people to absorb the information at a glance without feeling that it’s delaying their experience." + }, + { + "type": "paragraph", + "text": "Don’t let large downloads hinder onboarding. People want to start using your app or game immediately after first launching it, whether they participate in an onboarding flow or skip it. Consider including enough media and other content in your software package to prevent people from having to wait for downloads to complete before they can start interacting with your app or game. For guidance, see Launching." + }, + { + "type": "paragraph", + "text": "Avoid displaying licensing details within your onboarding flow. Let the App Store display agreements and disclaimers so people can read them before downloading your app or game. If you must include these items within the onboarding flow, integrate them in a balanced way that doesn’t disrupt the experience." + } + ] + }, + { + "heading": "Additional requests", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Postpone nonessential setup flows or customization steps. Provide reasonable default settings so most people can immediately start interacting with your app or game without performing additional configuration." + }, + { + "type": "paragraph", + "text": "If your app or game needs access to private data or resources before it can function, consider integrating the permission request into your onboarding flow. In this scenario, making the request during your onboarding flow gives you the opportunity to show people why your app or game needs their permission and the benefits of granting it. Otherwise, present a permission request when people first access the specific function that relies on private data or resources. For guidance, see Requesting permission." + }, + { + "type": "paragraph", + "text": "Prefer letting people experience your app or game before prompting them for ratings or purchases. People can be more likely to respond positively to such requests when they’ve had a chance to become engaged with your app or game." + } + ] + }, + { + "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": "Launching" + }, + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Offering help" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 10, 2024", + "Clarified different approaches to onboarding and added a guideline on displaying a splash screen." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "launching", + "url": "/design/human-interface-guidelines/launching" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/onboarding#Best-practices" + }, + { + "title": "Additional content", + "url": "/design/human-interface-guidelines/onboarding#Additional-content" + }, + { + "title": "Additional requests", + "url": "/design/human-interface-guidelines/onboarding#Additional-requests" + }, + { + "title": "Requesting permission", + "url": "/design/human-interface-guidelines/privacy#Requesting-permission" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/onboarding#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/onboarding#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/onboarding#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Offering help", + "url": "/design/human-interface-guidelines/offering-help" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/onboarding#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/onboarding#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Patterns", + "url": "https://developer.apple.com/design/human-interface-guidelines/patterns", + "category": "patterns", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "Charting data", + "url": "/design/human-interface-guidelines/charting-data" + }, + { + "title": "Collaboration and sharing", + "url": "/design/human-interface-guidelines/collaboration-and-sharing" + }, + { + "title": "Drag and drop", + "url": "/design/human-interface-guidelines/drag-and-drop" + }, + { + "title": "Entering data", + "url": "/design/human-interface-guidelines/entering-data" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "File management", + "url": "/design/human-interface-guidelines/file-management" + }, + { + "title": "Going full screen", + "url": "/design/human-interface-guidelines/going-full-screen" + }, + { + "title": "Launching", + "url": "/design/human-interface-guidelines/launching" + }, + { + "title": "Live-viewing apps", + "url": "/design/human-interface-guidelines/live-viewing-apps" + }, + { + "title": "Loading", + "url": "/design/human-interface-guidelines/loading" + }, + { + "title": "Managing accounts", + "url": "/design/human-interface-guidelines/managing-accounts" + }, + { + "title": "Managing notifications", + "url": "/design/human-interface-guidelines/managing-notifications" + }, + { + "title": "Modality", + "url": "/design/human-interface-guidelines/modality" + }, + { + "title": "Multitasking", + "url": "/design/human-interface-guidelines/multitasking" + }, + { + "title": "Offering help", + "url": "/design/human-interface-guidelines/offering-help" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Playing video", + "url": "/design/human-interface-guidelines/playing-video" + }, + { + "title": "Printing", + "url": "/design/human-interface-guidelines/printing" + }, + { + "title": "Ratings and reviews", + "url": "/design/human-interface-guidelines/ratings-and-reviews" + }, + { + "title": "Searching", + "url": "/design/human-interface-guidelines/searching" + }, + { + "title": "Settings", + "url": "/design/human-interface-guidelines/settings" + }, + { + "title": "Undo and redo", + "url": "/design/human-interface-guidelines/undo-and-redo" + }, + { + "title": "Workouts", + "url": "/design/human-interface-guidelines/workouts" + } + ], + "image_count": 0 + }, + { + "title": "Playing audio", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-audio", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Devices can play audio in a variety of ways, such as through internal or external speakers, headphones, and wirelessly through devices that use Bluetooth or AirPlay. To manipulate sound on their devices people use several types of controls, including volume buttons, the Ring/Silent switch on iPhone, headphone controls, the Control Center volume slider, and sound controls in third-party accessories. Whether sound is a primary part of your experience or an embellishment, you need to make sure it behaves as people expect as they make changes to volume and output." + }, + { + "type": "paragraph", + "text": "Silence. People switch a device to silent when they want to avoid being interrupted by unexpected sounds like ringtones and incoming message tones. In this scenario, they also want to silence nonessential sounds, such as keyboard clicks, sound effects, game soundtracks, and other audible feedback. When a device is in silent mode, it plays only the audio that people explicitly initiate, like media playback, alarms, and audio/video messaging." + }, + { + "type": "paragraph", + "text": "Volume. People expect their volume settings to affect all sound in the system — including music and in-app sound effects — regardless of the method they use to adjust the volume. An exception is the ringer volume on iPhone, which people can adjust separately in Settings." + }, + { + "type": "paragraph", + "text": "Headphones. People use headphones to keep their listening private and in some cases to free their hands. When connecting headphones, people expect sound to reroute automatically without interruption; when disconnecting headphones, they expect playback to pause immediately." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Adjust levels automatically when necessary — don’t adjust the overall volume. Your app can adjust relative, independent volume levels to achieve a great mix of audio, but the system volume always governs the final output." + }, + { + "type": "paragraph", + "text": "Permit rerouting of audio when possible. People often want to select a different audio output device. For example, they may want to listen to music through their living room stereo, car radio, or Apple TV. Support this capability unless there’s a compelling reason not to." + }, + { + "type": "paragraph", + "text": "Use the system-provided volume view to let people make audio adjustments. The volume view includes a volume-level slider and a control for rerouting audio output. You can customize the appearance of the slider. For developer guidance, see MPVolumeView." + }, + { + "type": "paragraph", + "text": "Choose an audio category that fits the way your app or game uses sound. Depending on the audio category you choose, your app’s sounds can mix with other audio, play while your app is in the background, or stop when people set the Ring/Silent switch to silent. As much as possible, pick a category that helps your app meet people’s expectations. For example, don’t make people stop listening to music from another app if you don’t need to. For developer guidance, see AVAudioSession.Category." + }, + { + "type": "table", + "rows": [ + [ + "Category", + "Meaning", + "Behavior" + ], + [ + "Solo ambient", + "Sound isn’t essential, but it silences other audio. For example, a game with a soundtrack.", + "Responds to the silence switch. Doesn’t mix with other sounds. Doesn’t play in the background." + ], + [ + "Ambient", + "Sound isn’t essential, and it doesn’t silence other audio. For example, a game that lets people play music from another app during gameplay in place of the game’s soundtrack.", + "Responds to the silence switch. Mixes with other sounds. Doesn’t play in the background." + ], + [ + "Playback", + "Sound is essential and might mix with other audio. For example, an audiobook or educational app that teaches a foreign language, which people might want to listen to after leaving the app.", + "Doesn’t respond to the silence switch. May or may not mix with other sounds. Can play in the background." + ], + [ + "Record", + "Sound is recorded. For example, a note-taking app that offers an audio recording mode. An app of this nature might switch its category to playback if it lets people play the recorded notes.", + "Doesn’t respond to the silence switch. Doesn’t mix with other sounds. Can record in the background." + ], + [ + "Play and record", + "Sound is recorded and played, potentially simultaneously. For example, an audio messaging or video calling app.", + "Doesn’t respond to the silence switch. May or may not mix with other sounds. Can record and play in the background." + ] + ] + }, + { + "type": "paragraph", + "text": "Respond to audio controls only when it makes sense. People can control audio playback from outside your app’s interface — such as in Control Center or with controls on their headphones — regardless of whether your app is in the foreground or background. If your app is actively playing audio, in a clear audio-related context, or connected to a device that uses Bluetooth or AirPlay, it’s fine to respond to audio controls. Otherwise, when people activate a control, avoid halting audio currently playing from another app." + }, + { + "type": "paragraph", + "text": "Avoid repurposing audio controls. People expect audio controls to behave consistently in all apps, so it’s essential to avoid redefining the meaning of an audio control in your app. If your app doesn’t support certain controls, don’t respond to them." + }, + { + "type": "paragraph", + "text": "Consider creating custom audio player controls only if you need to offer commands that the system doesn’t support. For example, you might want to define custom increments for skipping forward or backward, or present content that’s related to the playing audio, such as a sports score." + }, + { + "type": "paragraph", + "text": "Let other apps know when your app finishes playing temporary audio. If your app can temporarily interrupt the audio of other apps, be sure to flag your audio session in a way that lets other apps know when they can resume. For developer guidance, see notifyOthersOnDeactivation." + } + ] + }, + { + "heading": "Handling interruptions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Although most apps and games rely on the system’s default interruption behavior, you can customize this behavior to better accommodate your needs." + }, + { + "type": "paragraph", + "text": "Determine how to respond to audio-session interruptions. For example, if your app supports recording or other audio-related tasks that people don’t want interrupted, you can tell the system to avoid interrupting the currently playing audio for an incoming call unless people choose to accept it. Another example is a VoIP app, which must end a call when people close the Smart Folio of their iPad while they’re using the built-in microphone. Closing the Smart Folio automatically mutes the iPad microphone and by default interrupts the audio session associated with it. If a VoIP app restarts the audio session when people reopen their Smart Folio, it risks invading people’s privacy by unmuting the microphone without their knowledge. You can inspect an audio-session interruption to help determine the right way to respond; for developer guidance, see Handling audio interruptions." + }, + { + "type": "paragraph", + "text": "When an interruption ends, determine whether to resume audio playback automatically. Sometimes, audio from a different app can interrupt the audio your app is playing. An interruption can be resumable, like an incoming phone call, or nonresumable, like when people start a new music playlist. Use the interruption type and your app’s type to decide whether to resume playback automatically. For example, a media playback app that’s actively playing audio when an interruption occurs can check to be sure the type is resumable before continuing playback when the interruption ends. On the other hand, a game doesn’t need to check the interruption type before automatically resuming playback, because a game plays audio without an explicit user choice. For developer guidance, see shouldResume." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use the system’s sound services to play short sounds and vibrations. For developer guidance, see Audio Services." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In macOS, notification sounds mix with other audio by default." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In tvOS, the system plays audio only when people initiate it, through interactions within apps and games or when performing device calibrations. For example, tvOS doesn’t play sounds to accompany components like alerts or notifications." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Subtle, expressive sounds are everywhere in visionOS, enhancing experiences and providing essential feedback when people look at a virtual object and use gestures to interact with it. The system combines audio algorithms with information about a person’s physical surroundings to produce Spatial Audio, which is sound that people can perceive as coming from specific locations in space, not just from speakers." + }, + { + "type": "important", + "text": "ImportantIn visionOS, as in every platform, avoid communicating important information using only sound. Always provide additional ways to help people understand your app. For guidance, see Accessibility." + }, + { + "type": "paragraph", + "text": "In visionOS, audio playback from the Now Playing app pauses automatically when people close the app’s window, and audio from an app that isn’t the Now Playing app can duck when people look away from it to different app." + }, + { + "type": "paragraph", + "text": "Prefer playing sound. People generally choose to keep sounds audible while they’re wearing the device, so an app that doesn’t play sound — especially in an immersive moment — can feel lifeless and may even seem broken. Throughout the design process, look for opportunities to create meaningful sounds that aid navigation and help people understand the spatial qualities of your app." + }, + { + "type": "paragraph", + "text": "Design custom sounds for custom UI elements. In general, a system-provided element plays sound to help people locate it and receive feedback when they interact with it. To help people interact with your custom elements, design sounds that provide feedback and enhance the spatial experience of your app." + }, + { + "type": "paragraph", + "text": "Use Spatial Audio to create an intuitive, engaging experience. Because people can perceive Spatial Audio as coming from anywhere around them, it works especially well in a fully immersive context as a way to help an experience feel lifelike. Ambient audio provides pervasive sounds that can help anchor people in a virtual world and an audio source can sound like it comes from a specific object. As you build the soundscape for your app, consider using both types of audio." + }, + { + "type": "paragraph", + "text": "Consider defining a range of places from which your app sounds can originate. Spatial Audio helps people locate the object that’s making sound, whether it’s stationary or moving in space. For example, when people move an app window that’s playing audio, the sound continues to come directly from the window, wherever people move it." + }, + { + "type": "paragraph", + "text": "Consider varying sounds that people could perceive as repetitive over time. For example, the system subtly varies the pitch and volume of the virtual keyboard’s sounds, suggesting the different sounds a physical keyboard can make as people naturally vary the speed and forcefulness of their typing. An efficient way to achieve a pleasing variation in sound is to randomize a sound file’s pitch and volume during playback, instead of creating different files." + }, + { + "type": "paragraph", + "text": "Decide whether you need to play sound that’s fixed to the wearer or tracked by the wearer. People perceive fixed sound as if it’s pointed at them, regardless of the direction they look or the virtual objects they move. In contrast, people tend to perceive tracked sound as coming from a particular object, so moving the object closer or farther away changes what they hear. In general, you want to use tracked sound to enhance the realism of your experience, but there could be cases where fixed sound is a good choice. For example, Mindfulness uses fixed sound to envelop the wearer in an engaging, peaceful setting." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In watchOS, the system manages audio playback. An app can play short audio clips while it’s active and running in the foreground, or it can play longer audio that continues even when people lower their wrist or switch to another app. For developer guidance, see Playing Background Audio." + }, + { + "type": "paragraph", + "text": "Use the recommended encoding values for media assets. Specifically, use the 64 kbps HE-AAC (High-Efficiency Advanced Audio Coding) format to produce good-quality audio with lower data requirements." + }, + { + "type": "paragraph", + "text": "Consider presenting a Now Playing view so people can control current or recently played audio without leaving your app. The system-provided Now Playing view also displays information about the current audio source — which might be another app on a person’s Apple Watch or iPhone — and automatically selects the current or most recently used source. For developer guidance, see Adding a Now Playing View." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Playing video" + }, + { + "type": "paragraph", + "text": "Feedback" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Configuring your app for media playback — AVFoundation" + }, + { + "type": "paragraph", + "text": "AVAudioSession — AVFAudio" + } + ] + }, + { + "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/playing-audio#Best-practices" + }, + { + "title": "Handling interruptions", + "url": "/design/human-interface-guidelines/playing-audio#Handling-interruptions" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/playing-audio#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/playing-audio#iOS-iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/playing-audio#macOS" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/playing-audio#tvOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/playing-audio#visionOS" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/playing-audio#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/playing-audio#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/playing-audio#Related" + }, + { + "title": "Playing video", + "url": "/design/human-interface-guidelines/playing-video" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/playing-audio#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/playing-audio#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/playing-audio#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Playing haptics", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Depending on the platform and the device people are using, the system can play haptics in addition to visual and auditory feedback. For example, components like switches, sliders, and pickers automatically play haptic feedback on supported iPhone models; on Apple Watch, the Taptic Engine generates haptics for a number of built-in feedback patterns, which watchOS combines with an audible tone. On a Mac that’s equipped with a Force Touch trackpad, an app can play haptics while people drag content or when they force click to change the speed of media controls." + }, + { + "type": "paragraph", + "text": "In addition to built-in haptic capabilities, some external input devices can also play haptics. For example:" + }, + { + "type": "list", + "items": [ + "In an iPadOS, macOS, tvOS, or visionOS app or game, game controllers can provide haptic feedback (for developer guidance, see Playing Haptics on Game Controllers).", + "Apple Pencil Pro and some trackpads can provide haptic feedback when connected to certain iPad models. (For details on Apple Pencil features and compatibility, see Apple Pencil.)" + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use system-provided haptic patterns according to their documented meanings. People recognize standard haptics because the system plays them consistently on interactions with standard controls. If the documented use case for a pattern doesn’t make sense in your app or game, avoid using the pattern to mean something else. Instead, use a generic pattern or create your own, where supported. For guidance, see Custom haptics." + }, + { + "type": "paragraph", + "text": "Use haptics consistently throughout your app or game. It’s important to build a clear, causal relationship between each haptic and the action that causes it so people learn to associate certain haptic patterns with certain experiences. If a haptic doesn’t reinforce a cause-and-effect relationship, it can be confusing and seem gratuitous. For example, if your game plays a specific haptic pattern when a character fails to finish a mission, people associate that pattern with a negative outcome. If you use the same haptic pattern for a positive outcome like a level completion, people will be confused." + }, + { + "type": "paragraph", + "text": "Prefer using haptics to complement other feedback in your app or game. When visual, auditory, and tactile feedback are in harmony — as they generally are in the physical world — the user experience is more coherent and can seem more natural. For example, you generally want to match the intensity and sharpness of a haptic with the intensity and sharpness of the animation it accompanies. You can also synchronize sound with haptics; for developer guidance, see Delivering Rich App Experiences with Haptics." + }, + { + "type": "paragraph", + "text": "Avoid overusing haptics. Sometimes a haptic can feel just right when it happens occasionally, but become tiresome when it plays frequently. Doing user testing can help you discover a balance that most people appreciate. Often, the best haptic experience is one that people may not be conscious of, but miss when it’s turned off." + }, + { + "type": "paragraph", + "text": "In most apps, prefer playing short haptics that complement discrete events. Although long-running haptics that accompany a gameplay flow can enhance the experience, long-running haptics in an app can dilute the meaning of the feedback and distract people from their task. On Apple Pencil Pro, for example, continuous or long-lasting haptics don’t tend to clarify the writing or drawing experience and can even make holding the pencil less pleasant." + }, + { + "type": "paragraph", + "text": "Make haptics optional. Let people turn off or mute haptics, and make sure people can still enjoy your app or game without them." + }, + { + "type": "paragraph", + "text": "Be aware that playing haptics might impact other user experiences. By design, haptics produce enough physical force for people to feel the vibration. Ensure that haptic vibrations don’t disrupt experiences involving device features like the camera, gyroscope, or microphone." + } + ] + }, + { + "heading": "Custom haptics", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Games often use custom haptics to enhance gameplay. Although it’s less common, nongame apps might also use custom haptics to provide a richer, more delightful experience." + }, + { + "type": "paragraph", + "text": "You can design custom haptic patterns that vary dynamically, based on user input or context. For example, the impact players feel when a game character jumps from a tree can be stronger than when the character jumps in place, and substantial experiences — like a collision or a hit — can feel very different from subtle experiences like the approach of footsteps or a looming danger." + }, + { + "type": "paragraph", + "text": "There are two basic building blocks you can use to generate custom haptic patterns." + }, + { + "type": "list", + "items": [ + "Transient events are brief and compact, often feeling like taps or impulses. The experience of tapping the Flashlight button on the Home Screen is an example of a transient event.", + "Continuous events feel like sustained vibrations, such as the experience of the lasers effect in a message." + ] + }, + { + "type": "paragraph", + "text": "Regardless of the type of haptic event you use to generate a custom haptic, you can also control its sharpness and intensity. You can think of sharpness as a way to abstract a haptic experience into the waveform that produces the corresponding physical sensations. Specifying sharpness lets you relay to the system your intent for the experience. For example, you might use sharpness values to convey an experience that’s soft, rounded, or organic, or one that’s crisp, precise, or mechanical. As the term implies, intensity means the strength of the haptic." + }, + { + "type": "paragraph", + "text": "By combining transient and continuous events, varying sharpness and intensity, and including optional audio content, you can create a wide range of different haptic experiences. For developer guidance, see Core Haptics." + } + ] + }, + { + "heading": "iOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On supported iPhone models, you can add haptics to your experience in the following ways:" + }, + { + "type": "list", + "items": [ + "Use standard UI components — like toggles, sliders, and pickers — that play Apple-designed system haptics by default.", + "When it makes sense, use a feedback generator to play one of several predefined haptic patterns in the categories of notification, impact, and selection (for developer guidance, see UIFeedbackGenerator)." + ] + } + ] + }, + { + "heading": "Notification", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Notification haptics provide feedback about the outcome of a task or action, such as depositing a check or unlocking a vehicle." + }, + { + "type": "image", + "alt": "", + "caption": "Success. Indicates that a task or action has completed." + }, + { + "type": "image", + "alt": "", + "caption": "Warning. Indicates that a task or action has produced a warning of some kind." + }, + { + "type": "image", + "alt": "", + "caption": "Error. Indicates that an error has occurred." + } + ] + }, + { + "heading": "Impact", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Impact haptics provide a physical metaphor you can use to complement a visual experience. For example, people might feel a tap when a view snaps into place or a thud when two heavy objects collide." + }, + { + "type": "image", + "alt": "", + "caption": "Light. Indicates a collision between small or lightweight UI objects." + }, + { + "type": "image", + "alt": "", + "caption": "Medium. Indicates a collision between medium-sized or medium-weight UI objects." + }, + { + "type": "image", + "alt": "", + "caption": "Heavy. Indicates a collision between large or heavyweight UI objects." + }, + { + "type": "image", + "alt": "", + "caption": "Rigid. Indicates a collision between hard or inflexible UI objects." + }, + { + "type": "image", + "alt": "", + "caption": "Soft. Indicates a collision between soft or flexible UI objects." + } + ] + }, + { + "heading": "Selection", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Selection haptics provide feedback while the values of a UI element are changing." + }, + { + "type": "image", + "alt": "", + "caption": "Selection. Indicates that a UI element’s values are changing." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When a Magic Trackpad is available, your app can provide one of the three following haptic patterns in response to a drag operation or force click." + }, + { + "type": "table", + "rows": [ + [ + "Haptic feedback pattern", + "Description" + ], + [ + "Alignment", + "Indicates the alignment of a dragged item. For example, this pattern could be used in a drawing app when the people drag a shape into alignment with another shape. Other scenarios where this type of feedback could be used might include scaling an object to fit within specific dimensions, positioning an object at a preferred location, or reaching the beginning/end or minimum/maximum of something like a scrubber in a video app." + ], + [ + "Level change", + "Indicates movement between discrete levels of pressure. For example, as people press a fast-forward button on a video player, playback could increase or decrease and haptic feedback could be provided as different levels of pressure are reached." + ], + [ + "Generic", + "Intended for providing general feedback when the other patterns don’t apply." + ] + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see NSHapticFeedbackPerformer." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Apple Watch Series 4 and later provides haptic feedback for the Digital Crown, which gives people a more tactile experience as they scroll through content. By default, the system provides linear haptic detents that people can feel as they rotate the Digital Crown. Some system controls, like table views, provide detents as new items scroll onto the screen. For developer guidance, see WKHapticType." + }, + { + "type": "paragraph", + "text": "watchOS defines the following set of haptics, each of which conveys a specific meaning to people." + }, + { + "type": "paragraph", + "text": "Notification. Tells the person that something significant or out of the ordinary has happened and requires their attention. The system plays this same haptic when a local or remote notification arrives." + }, + { + "type": "paragraph", + "text": "Up. Tells the person that an important value increased above a significant threshold." + }, + { + "type": "paragraph", + "text": "Down. Tells the person that an important value decreased below a significant threshold." + }, + { + "type": "paragraph", + "text": "Success. Tells the person that an action completed successfully." + }, + { + "type": "paragraph", + "text": "Failure. Tells the person that an action failed." + }, + { + "type": "paragraph", + "text": "Retry. Tells the person that an action failed but they can retry it." + }, + { + "type": "paragraph", + "text": "Start. Tells the person that an activity started. Use this haptic when starting a timer or any other activity that a person can explicitly start and stop. The stop haptic usually follows this haptic." + }, + { + "type": "paragraph", + "text": "Stop. Tells the person that an activity stopped. Use this haptic when stopping a timer or other activity that the person previously started." + }, + { + "type": "paragraph", + "text": "Click. Provides the sensation of a dial clicking, helping you communicate progress at predefined increments or intervals. Overusing the click haptic tends to diminish its utility and can even be confusing when clicks overlap each other." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Gestures" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Core Haptics" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 7, 2024", + "Added guidance for playing haptics on Apple Pencil Pro." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "game controllers", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "Apple Pencil Pro", + "url": "/design/human-interface-guidelines/apple-pencil-and-scribble" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/playing-haptics#Best-practices" + }, + { + "title": "Custom haptics", + "url": "/design/human-interface-guidelines/playing-haptics#Custom-haptics" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/playing-haptics#Platform-considerations" + }, + { + "title": "iOS", + "url": "/design/human-interface-guidelines/playing-haptics#iOS" + }, + { + "title": "toggles", + "url": "https://developer.apple.com/design/human-interface-guidelines/toggles" + }, + { + "title": "sliders", + "url": "https://developer.apple.com/design/human-interface-guidelines/sliders" + }, + { + "title": "pickers", + "url": "https://developer.apple.com/design/human-interface-guidelines/pickers" + }, + { + "title": "notification", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Notification" + }, + { + "title": "impact", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Impact" + }, + { + "title": "selection", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Selection" + }, + { + "title": "Notification", + "url": "/design/human-interface-guidelines/playing-haptics#Notification" + }, + { + "title": "Impact", + "url": "/design/human-interface-guidelines/playing-haptics#Impact" + }, + { + "title": "Selection", + "url": "/design/human-interface-guidelines/playing-haptics#Selection" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/playing-haptics#macOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/playing-haptics#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/playing-haptics#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/playing-haptics#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/playing-haptics#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/playing-haptics#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/playing-haptics#Change-log" + } + ], + "image_count": 9 + }, + { + "title": "Playing video", + "url": "https://developer.apple.com/design/human-interface-guidelines/playing-video", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The system provides video players designed for you to use to embed playback experiences within your app or game in iOS, iPadOS, macOS, tvOS, and visionOS. You can also offer your content through the TV app in these platforms, which gives people a convenient and consistent viewing experience." + }, + { + "type": "paragraph", + "text": "The system-provided video players support different aspect-ratio playback modes and in most platforms, Picture in Picture (PiP) viewing mode. Although people can switch modes during playback, by default, the system selects one of the following playback modes based on a video’s aspect ratio:" + }, + { + "type": "list", + "items": [ + "In full-screen — or aspect-fill — mode, the video scales to fill the display, and some edge cropping may occur. This mode is the default for wide video (2:1 through 2.40:1). For developer guidance, see resizeAspectFill.", + "In fit-to-screen — or aspect — mode, the entire video is visible onscreen, and letterboxing or pillarboxing occurs as needed. This mode is the default for standard video (4:3, 16:9, and anything up to 2:1) and ultrawide video (anything above 2.40:1). For developer guidance, see resizeAspect." + ] + }, + { + "type": "paragraph", + "text": "In visionOS and tvOS, the built-in video player also provides transport controls, which let people perform playback tasks, like turning on subtitles or changing the audio language, and actions, like adding a show to a library or favoriting a clip. Below the transport controls, the video player displays content tabs, like Info, Episodes, or Chapters, that can provide supporting information and help streamline navigation. In visionOS, the transport controls appear as an ornament." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use the system video player to give people a familiar and convenient experience. The built-in video player provides an exceptional video playback experience that offers consistent interactions and behaviors that let people concentrate on enjoying immersive content. If your app truly requires a custom video player, reference the behavior and interface of the system video player to help you provide an experience that people can instantly understand. A custom experience that diverges slightly from the system-provided experience can cause frustration because people don’t know which of their habitual interactions they can continue to use." + }, + { + "type": "paragraph", + "text": "Always display video content at its original aspect ratio. When video content uses embedded letterbox or pillarbox padding to conform to a specific aspect ratio, the system may be unable to correctly scale the video based on the current playback mode. Padding embedded within the video frame can cause videos to appear smaller in both full-screen and fit-to-screen modes. It also prevents videos from displaying correctly in edge-to-edge, non-full-screen contexts, like Picture in Picture mode on iPad." + }, + { + "type": "paragraph", + "text": "Here are some examples that show how padding can affect video display on iPhone Xs." + }, + { + "type": "paragraph", + "text": "4:3 video in full-screen viewing mode" + }, + { + "type": "paragraph", + "text": "4:3 video with embedded padding, in full-screen viewing mode" + }, + { + "type": "paragraph", + "text": "21:9 video in fit-to-screen viewing mode" + }, + { + "type": "paragraph", + "text": "21:9 video with embedded padding, in fit-to-screen viewing mode" + }, + { + "type": "paragraph", + "text": "Provide additional information when it adds value. In iOS, iPadOS, tvOS, and visionOS, you can customize a video’s additional information by providing an image, title, description, and other useful information. In general, restrict this content so that it doesn’t obscure media playback. For developer guidance, see externalMetadata." + }, + { + "type": "paragraph", + "text": "Support the interactions people expect, regardless of the input device they’re using to control playback. For example, people expect to press Space on a connected keyboard to play or pause media playback on Apple Vision Pro, Mac, iPhone, iPad, and Apple TV. Similarly, people expect to move through their media on Apple TV by making familiar, intuitive gestures with the Siri Remote. For guidance, see Keyboards and Remotes." + }, + { + "type": "paragraph", + "text": "If people need to access playback options or content-specific information in your tvOS app, consider adding a transport control or a custom content tab. People typically open a transport control or content tab while they’re watching a video, so it’s essential to provide only the most useful actions and information. Help people return quickly to the viewing experience by making sure your actions don’t take more than a step or two and your content is succinct. Use a transport control to support a playback-related action like favoriting a video; use custom content tabs to display supplementary information or recommendations." + }, + { + "type": "paragraph", + "text": "Avoid allowing audio from different sources to mix as viewers switch between modes. Mixed audio is an unpleasant and frustrating user experience. In general, audio mixes when at least one of the audio sources fails to handle secondary audio correctly. Here is a typical scenario: While watching a full-screen video, the viewer moves it into the PiP window, where the system automatically mutes the video. In the full-screen window, the viewer starts a game that plays background music, then switches to the PiP window and unmutes the video. If the game doesn’t handle secondary audio appropriately, its audio mixes with the audio from the unmuted video. For developer guidance, see silenceSecondaryAudioHintNotification." + } + ] + }, + { + "heading": "Integrating with the TV app", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The TV app provides global access to favorite, recently played, and recommended video content from across the system. When people initiate content playback within your app, the TV app automatically opens your app and transitions to it. Follow these guidelines to help the TV app experience feel like an integrated part of your app." + }, + { + "type": "paragraph", + "text": "Ensure a smooth transition to your app. The TV app fades to black when transitioning to your app and doesn’t show your app’s launch screen. Maintain visual continuity with this transition by immediately presenting your own black screen before starting to play or resume content." + }, + { + "type": "paragraph", + "text": "Show the expected content immediately. People expect the content they choose to begin playing as soon as the transition to your app completes, especially when resuming playback. Jump right from your app’s black screen into content, and avoid displaying splash screens, detail screens, intro animations, or any other barriers that make it take longer to reach content. In rare situations where you must display an interstitial element before the selected media plays, people can choose Select to step through the element, or choose Play if they want to skip the interstitial content and start playback." + }, + { + "type": "paragraph", + "text": "Avoid asking people if they want to resume playback. If playback can be resumed, do so automatically without prompting for confirmation." + }, + { + "type": "paragraph", + "text": "Play or pause playback when people press Space on a connected Bluetooth keyboard. Pressing Space to control media playback is an interaction people expect, regardless of the keyboard they’re using." + }, + { + "type": "paragraph", + "text": "Make sure content plays for the correct viewer. If your app supports multiple user profiles, the TV app can specify a profile when issuing a playback request. Make your app automatically switch to this profile before starting playback. If a playback request doesn’t specify a profile, ask the viewer to choose one before playback begins so this information is available in the future." + }, + { + "type": "paragraph", + "text": "Use the previous end time when resuming playback of a long video clip. Resuming playback at the previous stopping point lets people quickly continue where they left off." + } + ] + }, + { + "heading": "Loading content", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Avoid displaying loading screens when possible. A loading screen is unnecessary if your content loads quickly, but if loading takes more than two seconds, consider showing a black loading screen with a centered activity spinner and no surrounding content." + }, + { + "type": "paragraph", + "text": "Start playback immediately. If you must display a loading screen, display it only until enough content loads for playback to begin. Continue loading remaining content in the background." + }, + { + "type": "paragraph", + "text": "Minimize loading screen content. If you include branding or images on your loading screen, do so minimally while maintaining the black background that helps provide a seamless transition to playback." + } + ] + }, + { + "heading": "Exiting playback", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "After exiting playback, people remain in your app rather than returning to the TV app, so it’s a good idea to help them avoid becoming disoriented." + }, + { + "type": "paragraph", + "text": "Show a contextually relevant screen. When exiting playback, display a detail view for the content the viewer was just watching and include an option to resume playback. If a detail view isn’t available, show either a menu that lists this content or your app’s main menu." + }, + { + "type": "paragraph", + "text": "Be prepared for an immediate exit. Prepare an exit view as soon as possible after receiving a playback notification so you’re ready to display the view if people exit immediately after playback begins." + } + ] + }, + { + "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": "Defer to content when displaying logos or noninteractive overlays above video. A small, unobtrusive logo or countdown timer may be appropriate for your video, but avoid large, distracting overlays that don’t enhance the viewing experience. Also, be aware that some devices are prone to image retention, so it’s generally better to keep overlays short and to prefer translucent graphics in Standard Dynamic Range (SDR) to bright, opaque content." + }, + { + "type": "paragraph", + "text": "Show interactive overlays gracefully. Some videos display interactive overlays, such as quizzes, surveys, and progress check-ins. For the best user experience, implement a minimum delay of 0.5 seconds to pause playing media, and display an interactive overlay. Give people a clear way to dismiss the overlay and resume media playback after they finish interacting." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Help people stay comfortable when playing video in your app. Often, an app doesn’t control the content in the videos it plays, but you can help people stay comfortable by:" + }, + { + "type": "list", + "items": [ + "Letting them choose when to start playing a video", + "Using a small window for playback, letting people resize it if they want", + "Making sure people can see their surroundings during playback" + ] + }, + { + "type": "paragraph", + "text": "In a fully immersive experience, avoid letting virtual content obscure playback or transport controls. In a fully immersive context, the system automatically places the video player at a predictable location that provides an optimal viewing experience. Use this location to help make sure that no virtual content occludes the default playback or transport controls in the ornament near the bottom of the player." + }, + { + "type": "paragraph", + "text": "Avoid automatically starting a fully immersive video playback experience. People need control over their experience and they’re unlikely to appreciate being launched into a fully immersive video without warning." + }, + { + "type": "paragraph", + "text": "Create a thumbnail track if you want to support scrubbing. The system displays thumbnails as people scrub to different times in the video, helping them choose the section they want. To improve performance, supply a set of thumbnails that each measure 160 px in width. For developer guidance, see HTTP Live Streaming (HLS) Authoring Specification for Apple Devices > Trick Play." + }, + { + "type": "paragraph", + "text": "Avoid expanding an inline video player to fill a window. When you display the system-provided player view in a window, playback controls appear in the same plane as the player view and not in an ornament that floats above the window. Inline video needs to be 2D and you want to make sure that window content remains visible around the player so people don’t expect a more immersive playback experience. For developer guidance, see AVPlayerViewController." + }, + { + "type": "paragraph", + "text": "Use a RealityKit video player if you need to play video in a view like a splash screen or a transitional view. In situations like these, people generally expect the video to lead into the next experience, so they don’t need playback controls or system-provided integration, like dimming and view anchoring. The RealityKit video player automatically uses the correct aspect ratio for both 2D and 3D video and supports closed captions. RealityKit can also help you play video as a special effect on the surface of a custom view or object. For developer guidance, see RealityKit." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In watchOS, the system manages video playback. Apps can play short video clips while the app is active and running in the foreground. You can use a movie element to embed clips in your interface and play video inline, or you can play a clip in a separate interface. For developer guidance, see VideoPlayer." + }, + { + "type": "paragraph", + "text": "Keep video clips short. Prefer shorter clips of no longer than 30 seconds. Long clips consume more disk space and require people to keep their wrists raised for longer periods of time, which can cause fatigue." + }, + { + "type": "paragraph", + "text": "Use the recommended sizes and encoding values for media assets. In particular, avoid scaling video clips, which affects performance and results in a suboptimal appearance. The following table lists the recommended encoding and resolution values for video assets. The audio encoding values apply to both movies and audio-only assets." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Video codec", + "H.264 High Profile" + ], + [ + "Video bit rate", + "160 kbps at up to 30 fps" + ], + [ + "Resolution (full screen)", + "208x260 px (portrait orientation)" + ], + [ + "Resolution (16:9)", + "320x180 px (landscape orientation)" + ], + [ + "Audio", + "64 kbps HE-AAC" + ] + ] + }, + { + "type": "paragraph", + "text": "Avoid creating a poster image that looks like a system control. You want people to understand that they can tap a movie element for playback; you don’t want to confuse people by making movie elements look like something else." + }, + { + "type": "paragraph", + "text": "Consider creating a poster image that represents a video clip’s contents. When people tap a poster image, the system replaces the image with the video and begins inline playback. A relevant poster image can help people make an informed decision about whether to view the video. In general, avoid creating a poster image that has nothing to do with the content or that people might mistake for a control." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Playing audio" + }, + { + "type": "paragraph", + "text": "Feedback" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Configuring your app for media playback — AVFoundation" + }, + { + "type": "paragraph", + "text": "AVKit" + }, + { + "type": "paragraph", + "text": "HTTP Live Streaming" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Corrected the recommended width for a thumbnail in visionOS." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "ornament", + "url": "/design/human-interface-guidelines/ornaments" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/playing-video#Best-practices" + }, + { + "title": "Integrating with the TV app", + "url": "/design/human-interface-guidelines/playing-video#Integrating-with-the-TV-app" + }, + { + "title": "Loading content", + "url": "/design/human-interface-guidelines/playing-video#Loading-content" + }, + { + "title": "Exiting playback", + "url": "/design/human-interface-guidelines/playing-video#Exiting-playback" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/playing-video#Platform-considerations" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/playing-video#tvOS" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/playing-video#visionOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/playing-video#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/playing-video#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/playing-video#Related" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/playing-video#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/playing-video#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/playing-video#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Printing", + "url": "https://developer.apple.com/design/human-interface-guidelines/printing", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make printing discoverable. Help people find your print action by placing it in standard system locations. For example, include a Print item in your macOS app’s File menu; in your iOS or iPadOS app, add a toolbar button that opens an action sheet. If your macOS app has a toolbar, you might want to put a Print button there, too, but consider making it an optional button that people can add when they customize the toolbar." + }, + { + "type": "paragraph", + "text": "Present a printing option only when it’s possible. If there’s nothing onscreen to print, or no printers are available, dim the Print item in a macOS app’s File menu and remove the Print action from the Action sheet in an iOS or iPadOS app. If you implement a custom print button, dim or hide it when printing isn’t possible." + }, + { + "type": "paragraph", + "text": "Present relevant printing options. If it makes sense to offer options like selecting a page range, requesting multiple copies, or printing on both sides — and the printer supports the options — use the system-provided view to present them." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If your macOS app offers app-specific print options that the system doesn’t offer, consider creating a custom category for the print panel. By default, the print panel offers several categories of settings, such as Layout, Paper Handling, and Media & Quality. Give your custom category a unique name, such as your app name, and include options that help people have a great print experience in your app. For example, Keynote offers presentation-specific options, like the ability to print presenter notes, slide backgrounds, and skipped slides." + }, + { + "type": "paragraph", + "text": "If your app supports document-specific page settings, consider presenting a page setup dialog. A page setup dialog includes rarely changed settings for page size, orientation, and scaling that apply to printing a particular document. If this makes sense in your app, avoid implementing features the system already provides. For example, you don’t need to include options like changing the page orientation or printing in reverse order because the system implements these options." + }, + { + "type": "paragraph", + "text": "Make sure interdependencies between options are clear. For example, if double-sided printing is available, an option to print on transparencies becomes unavailable." + }, + { + "type": "paragraph", + "text": "Separate advanced features from frequently used features. Consider using a disclosure control to hide advanced options until they’re needed. Label advanced options as Advanced Options." + }, + { + "type": "paragraph", + "text": "Consider letting people preview the effect of a setting. For example, you could update a thumbnail image to show the effect of changing a tone control." + }, + { + "type": "paragraph", + "text": "Consider storing modified settings with the document. At minimum, it makes sense to store print settings until the document is closed in case people want to print it again." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "File management" + }, + { + "type": "paragraph", + "text": "File menu" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "UIPrintInteractionController — UIKit" + }, + { + "type": "paragraph", + "text": "NSDocument — AppKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/printing#Best-practices" + }, + { + "title": "action sheet", + "url": "https://developer.apple.com/design/human-interface-guidelines/action-sheets" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/printing#Platform-considerations" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/printing#macOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/printing#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/printing#Related" + }, + { + "title": "File management", + "url": "/design/human-interface-guidelines/file-management" + }, + { + "title": "File menu", + "url": "/design/human-interface-guidelines/the-menu-bar#File-menu" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/printing#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Ratings and reviews", + "url": "https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Delivering a great overall experience is the best way to encourage positive ratings and reviews, but it’s also crucial to choose the right time to ask people for feedback. Although every app is different, some possible ways to do this involve looking at how many times or how frequently people launch your app, the number of features someone explores, or the number of tasks they complete." + }, + { + "type": "paragraph", + "text": "People can always rate your app within the App Store." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Ask for a rating only after people have demonstrated engagement with your app or game. For example, you might prompt people when they complete a game level or a significant task. Avoid asking for a rating on first launch or during onboarding, because people haven’t had enough time to gain a clear understanding of your app’s value or form an opinion. People may even be more likely to leave negative feedback if they feel an app is asking for a rating before they get a chance to use it." + }, + { + "type": "paragraph", + "text": "Avoid interrupting people while they’re performing a task or playing a game. Asking for feedback can disrupt the user experience and feel like a burden. Look for natural breaks or stopping points in your app or game where a rating request is less likely to be bothersome." + }, + { + "type": "paragraph", + "text": "Avoid pestering people. Repeated rating requests can be irritating, and may even negatively influence people’s opinion of your app. Consider allowing at least a week or two between requests, prompting again after people demonstrate additional engagement with your experience." + }, + { + "type": "paragraph", + "text": "Prefer the system-provided prompt. iOS, iPadOS, and macOS offer a consistent, nonintrusive way for apps and games to request ratings and reviews. When you identify places in your experience where it makes sense to ask for feedback, the system checks for previous feedback and — if there isn’t any — displays an in-app prompt that asks for a rating and an optional written review. People can supply feedback or dismiss the prompt with a single tap or click; they can also opt out of receiving these prompts for all apps they have installed. The system automatically limits the display of the prompt to three occurrences per app within a 365-day period. For developer guidance, see RequestReviewAction." + }, + { + "type": "paragraph", + "text": "Weigh the benefits of resetting your summary rating against the potential disadvantage of showing fewer ratings. When you release a new version of your app or game, you can reset the summary of individual ratings you received since the last reset. Although resetting means that the ratings reflect the current version, it also tends to result in having fewer ratings overall, which can discourage some people from downloading your app. For developer guidance, see Reset app summary rating." + } + ] + }, + { + "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": "Ratings, reviews, and responses" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "RequestReviewAction — StoreKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Added artwork." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/ratings-and-reviews#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Searching", + "url": "https://developer.apple.com/design/human-interface-guidelines/searching", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "To search for content within an app, people generally expect to use a search field. When it makes sense, you can personalize the search experience by using what you know about how people interact with your app. For example, you might display recent searches, search suggestions, completions, or corrections based on terms people searched earlier in your app." + }, + { + "type": "paragraph", + "text": "In some cases, people appreciate the ability to scope a search or filter the results. For example, people might want to search for items by specifying attributes like creation date, file size, or file type. For guidance, see Scope controls and tokens. You can also help people find content within an open document or file by implementing ways to find content in a window or page in your iOS, iPadOS, or macOS app." + }, + { + "type": "paragraph", + "text": "In iOS, iPadOS, and macOS, Spotlight helps people find content across all apps in the system and on the web. When you index and provide information about your app’s content, people can use Spotlight to find content your app contains without opening it first. For guidance, see Systemwide search." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If search is important, consider making it a primary action. For example, in the Apple TV, Photos, and Phone apps in iOS, search occupies a distinct tab in the tab bar. In the Notes app, a search field is in the toolbar, making search clearly visible and easily accessible." + }, + { + "type": "paragraph", + "text": "Aim to make your app’s content searchable through a single location. People appreciate having one clearly identified location they can use to find anything in your app that they are looking for. For apps with clearly distinct sections, it may still be useful to offer a local search. For example, search acts as a filter on the current view when searching your Recents and Contacts in the iOS Phone app." + }, + { + "type": "paragraph", + "text": "Use placeholder text to indicate what content is searchable. For example, the Apple TV app includes the placeholder text Shows, Movies, and More." + }, + { + "type": "paragraph", + "text": "Clearly display the current scope of a search. Use a descriptive placeholder text, a scope control, or a title to help reinforce what someone is currently searching. For example, in the Mail app there is always a clear reference to the mailbox someone is searching." + }, + { + "type": "paragraph", + "text": "Provide suggestions to make searching easier. When you display a personʼs recent searches or offer search suggestions both before and while they’re typing, you can help people search faster and type less. For developer guidance, see searchSuggestions(_:)." + }, + { + "type": "paragraph", + "text": "Take privacy into consideration before displaying search history. People might not appreciate having their search history appear where others might see it. Depending on the context, consider providing other ways to narrow the search instead. If you do show search history, provide a way for people to clear it if they want." + } + ] + }, + { + "heading": "Systemwide search", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make your app’s content searchable in Spotlight. You can share content with Spotlight by making it indexable and specifying descriptive attributes known as metadata. Spotlight extracts, stores, and organizes this information to allow for fast, comprehensive searches." + }, + { + "type": "paragraph", + "text": "Define metadata for custom file types you handle. Supply a Spotlight File Importer plug-in that describes the types of metadata your file format contains. For developer guidance, see CSImportExtension." + }, + { + "type": "paragraph", + "text": "Use Spotlight to offer advanced file-search capabilities within the context of your app. For example, you might include a button that instantly initiates a Spotlight search based on the current selection. You might then display a custom view that presents the search results or a filtered subset of them." + }, + { + "type": "paragraph", + "text": "Prefer using the system-provided open and save views. The system-provided open and save views generally include a built-in search field that people can use to search and filter the entire system. For related guidance, see File management." + }, + { + "type": "paragraph", + "text": "Implement a Quick Look generator if your app produces custom file types. A Quick Look generator helps Spotlight and other apps show previews of your documents. For developer guidance, see Quick Look." + } + ] + }, + { + "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": "Search fields" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adding your app’s content to Spotlight indexes — Core Spotlight" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated best practices with general guidance from Search fields, and reorganized guidance for systemwide search." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "search field", + "url": "/design/human-interface-guidelines/search-fields" + }, + { + "title": "Scope controls and tokens", + "url": "/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens" + }, + { + "title": "Systemwide search", + "url": "/design/human-interface-guidelines/searching#Systemwide-search" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/searching#Best-practices" + }, + { + "title": "tab bar", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "toolbar", + "url": "/design/human-interface-guidelines/toolbars" + }, + { + "title": "File management", + "url": "/design/human-interface-guidelines/file-management" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/searching#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/searching#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/searching#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/searching#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/searching#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/searching#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Settings", + "url": "https://developer.apple.com/design/human-interface-guidelines/settings", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On all Apple platforms, the system-provided Settings app lets people adjust things like the overall appearance of the system, network connections, account details, accessibility requirements, and language and region settings. On some platforms, the system-provided Settings app can also include settings for specific apps and games, often letting people adjust whether the app or game can access location information, use device features like microphone or camera, and integrate with system features like notifications, Siri, or Search." + }, + { + "type": "paragraph", + "text": "When necessary, you can provide a custom settings area within your app or game to offer general settings that affect your overall experience, like interface style or game-saving behavior. If you need to offer settings that affect only a specific task, you can provide these options within the task itself, so people don’t have to leave the experience to customize it." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Aim to provide default settings that give the best experience to the largest number of people. For example, you can automatically maximize performance for the device your game is running on instead of asking players to make this choice after your game launches (for developer guidance, see Improving your game’s graphics performance and settings). When you choose appropriate default settings, people may not have to make any adjustments before they can start enjoying your app or game." + }, + { + "type": "paragraph", + "text": "Minimize the number of settings you offer. Although people appreciate having control over an app or game, too many settings can make the experience feel less approachable, while also making it hard to find a particular setting." + }, + { + "type": "paragraph", + "text": "Make settings available in ways people expect. For example, when a physical keyboard is connected, people often use the standard Command-Comma (,) keyboard shortcut to open an app’s settings, whereas in a game, players often use the Esc (Escape) key." + }, + { + "type": "paragraph", + "text": "Avoid using settings to ask for setup information you can get in other ways. For example, a game can automatically detect a connected controller or accessory instead of asking the player to identify it; an app can detect whether people are currently using Dark Mode." + }, + { + "type": "paragraph", + "text": "Respect people’s systemwide settings and avoid including redundant versions of them in your custom settings area. People expect to use the system-provided Settings app to manage global options like accessibility accommodations, scrolling behavior, and authentication methods, and they expect all apps and games to adhere to their choices. Including custom versions of global options in your settings area is likely to confuse people because it implies that systemwide settings may not apply to your app or game and that changing your custom version of a global setting may affect other apps and games, too." + } + ] + }, + { + "heading": "General settings", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Put general, infrequently changed settings in your custom settings area. People must suspend what they’re doing to open an app’s or game’s settings area, so you want to include options that people don’t need to change all the time. For example, an app might list options for adjusting window configuration; a game might let players specify game-saving behavior or keyboard mappings; both apps and games might offer options related to people’s accounts." + } + ] + }, + { + "heading": "Task-specific options", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When possible, prefer letting people modify task-specific options without going to your settings area. For example, if people can adjust things like showing or hiding parts of the current view, reordering a collection of items, or filtering a list, make these options available in the screens they affect, where they’re discoverable and convenient. Putting this type of option in a separate settings area disconnects it from its context, requiring people to suspend their task to make adjustments, and often hiding the results until people resume the task." + }, + { + "type": "note", + "text": "NoteIn games, players tend to adjust their approach to a specific task as part of the gameplay, not as a settings option to change." + } + ] + }, + { + "heading": "System settings", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Add only the most rarely changed options to the system-provided Settings app. If it makes sense to add your app’s or game’s settings to the system-provided Settings app, consider providing a button that opens it directly from your interface." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When people choose the Settings item in your app’s or game’s App menu, your custom settings window opens. Typically, a custom settings window contains a toolbar that includes buttons for switching between views — called panes — that each contain a group of related settings." + }, + { + "type": "paragraph", + "text": "Include a settings item in the App menu. Avoid adding settings buttons to a window’s toolbar, because doing so decreases the space available for essential commands that people use frequently. If you provide document-level options, add this item to your app’s File menu." + }, + { + "type": "paragraph", + "text": "Dim a settings window’s minimize and maximize buttons. It’s quick to open a custom settings window using the standard Command–Comma (,) keyboard command, so there’s no need to keep the window in the Dock, and because a settings window accommodates the size of the current pane, people don’t need to expand the window to see more." + }, + { + "type": "paragraph", + "text": "In your settings window, use a noncustomizable toolbar that remains visible and always indicates the active toolbar button. A settings window’s toolbar identifies the areas people can customize and helps people navigate among those areas. People rely on a stable settings interface to help them find what they need." + }, + { + "type": "paragraph", + "text": "Update the window’s title to reflect the currently visible pane. If your settings window doesn’t have multiple panes, use the title App Name Settings." + }, + { + "type": "paragraph", + "text": "Restore the most recently viewed pane. People often adjust related settings more than once, so it can be convenient when a settings window opens to the last pane people used." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In watchOS, apps and games don’t add custom settings to the system-provided Settings app. As an alternative, consider making a small number of essential options available at the bottom of the main view or letting people use a More menu to reconfigure objects." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Onboarding" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Settings — SwiftUI" + }, + { + "type": "paragraph", + "text": "UserDefaults — Foundation" + }, + { + "type": "paragraph", + "text": "Preference Panes" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 10, 2024", + "Reorganized some guidance into new topics and added game-specific examples." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/settings#Best-practices" + }, + { + "title": "General settings", + "url": "/design/human-interface-guidelines/settings#General-settings" + }, + { + "title": "Task-specific options", + "url": "/design/human-interface-guidelines/settings#Task-specific-options" + }, + { + "title": "System settings", + "url": "/design/human-interface-guidelines/settings#System-settings" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/settings#Platform-considerations" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/settings#macOS" + }, + { + "title": "App menu", + "url": "/design/human-interface-guidelines/the-menu-bar#App-menu" + }, + { + "title": "File menu", + "url": "/design/human-interface-guidelines/the-menu-bar#File-menu" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/settings#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/settings#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/settings#Related" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/settings#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/settings#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Undo and redo", + "url": "https://developer.apple.com/design/human-interface-guidelines/undo-and-redo", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People expect undo and redo to let them reverse their recent actions, so they’re likely to try undoing — often multiple times — until something changes. In a situation like this, people might not remember which of their previous actions an undo is targeting, which can lead to unintended changes and frustration. To help people remain in control, it’s essential to help people predict the outcome of undoing and redoing and to highlight the results." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Help people predict the results of undo and redo as much as possible. On iPhone, for example, you can describe the result in the alert that displays when people shake the device, giving them the option of performing the undo or canceling it. If you provide undo and redo menu items, you can modify the menu item labels to identify the result. For example, a document-based app might use menu item labels like Undo Typing or Redo Bold." + }, + { + "type": "paragraph", + "text": "Show the results of an undo or redo. Sometimes, the most recent action that people want to undo affects content or an area that’s no longer visible. In cases like this, it’s crucial to highlight the result of each undo and redo to keep people from thinking that the action had no effect, which can lead them to perform it repeatedly. For example, if people undo after deleting a paragraph in a document area that’s no longer onscreen, you might scroll the document to show the restored paragraph." + }, + { + "type": "paragraph", + "text": "Let people undo multiple times. Avoid placing unnecessary limits on the number of times people can undo or redo. People generally expect to undo every action they’ve performed since taking a logical step like opening a document or saving their work." + }, + { + "type": "paragraph", + "text": "Consider giving people the option to revert multiple changes at once. In some scenarios, people might appreciate the ability to undo a batch of discrete but related actions — like incremental adjustments to a single property or attribute — so they don’t have to undo each individual adjustment. In other cases, it can make sense to give people a convenient way to undo all the changes they made since opening a document or saving their work." + }, + { + "type": "paragraph", + "text": "Provide undo and redo buttons only when necessary. People generally expect to initiate undo and redo in system-supported ways, such as choosing the items in a macOS app’s Edit menu, using keyboard shortcuts on a Mac or iPad, or shaking their iPhone. If it’s important to provide dedicated undo and redo buttons in your app, use the standard system-provided symbols and put the buttons in a toolbar." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for visionOS. Not supported in tvOS or watchOS." + } + ] + }, + { + "heading": "iOS, iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Avoid redefining standard gestures for undo and redo. For example, people can use a three-finger swipe to initiate an undo or redo, or shake their iPhone. As with all standard gestures, redefining them in your interface runs the risk of confusing people and making your experience unpredictable." + }, + { + "type": "paragraph", + "text": "Briefly and precisely describe the operation to be undone or redone. The undo and redo alert title automatically includes a prefix of “Undo ” or “Redo ” (including the trailing space). You need to provide an additional word or two that describes what’s being undone or redone, to appear after this prefix. For example, you might create alert titles such as “Undo Name” or “Redo Address Change.”" + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Place undo and redo commands in the Edit menu and support the standard keyboard shortcuts. Mac users expect to find undo and redo at the top of the Edit menu; they also expect to use Command–Z and Shift–Command–Z to perform undo and redo, respectively." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Feedback" + }, + { + "type": "paragraph", + "text": "Pointing devices" + }, + { + "type": "paragraph", + "text": "Standard keyboard shortcuts" + }, + { + "type": "paragraph", + "text": "Edit menu" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "UndoManager — Foundation" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/undo-and-redo#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/undo-and-redo#Platform-considerations" + }, + { + "title": "iOS, iPadOS", + "url": "/design/human-interface-guidelines/undo-and-redo#iOS-iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/undo-and-redo#macOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/undo-and-redo#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/undo-and-redo#Related" + }, + { + "title": "Feedback", + "url": "/design/human-interface-guidelines/feedback" + }, + { + "title": "Pointing devices", + "url": "/design/human-interface-guidelines/pointing-devices" + }, + { + "title": "Standard keyboard shortcuts", + "url": "/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts" + }, + { + "title": "Edit menu", + "url": "/design/human-interface-guidelines/the-menu-bar#Edit-menu" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/undo-and-redo#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/undo-and-redo#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Windows", + "url": "https://developer.apple.com/design/human-interface-guidelines/windows", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In iPadOS, macOS, and visionOS, windows help define the visual boundaries of app content and separate it from other areas of the system, and enable multitasking workflows both within and between apps. Windows include system-provided interface elements such as frames and window controls that let people open, close, resize, and relocate them." + }, + { + "type": "paragraph", + "text": "Conceptually, apps use two types of windows to display content:" + }, + { + "type": "list", + "items": [ + "A primary window presents the main navigation and content of an app, and actions associated with them.", + "An auxiliary window presents a specific task or area in an app. Dedicated to one experience, an auxiliary window doesn’t allow navigation to other app areas, and it typically includes a button people use to close it after completing the task." + ] + }, + { + "type": "paragraph", + "text": "For guidance laying out content within a window on any platform, see Layout; for guidance laying out content in Apple Vision Pro space, see Spatial layout. For developer guidance, see Windows." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make sure that your windows adapt fluidly to different sizes to support multitasking and multiwindow workflows. For guidance, see Layout and Multitasking." + }, + { + "type": "paragraph", + "text": "Choose the right moment to open a new window. Opening content in a separate window is great for helping people multitask or preserve context. For example, Mail opens a new window whenever someone selects the Compose action, so both the new message and the existing email are visible at the same time. However, opening new windows excessively creates clutter and can make navigating your app more confusing. Avoid opening new windows as default behavior unless it makes sense for your app." + }, + { + "type": "paragraph", + "text": "Consider providing the option to view content in a new window. While it’s best to avoid opening new windows as default behavior unless it benefits your user experience, it’s also great to give people the flexibility of viewing content in multiple ways. Consider letting people view content in a new window using a command in a context menu or in the File menu. For developer guidance, see OpenWindowAction." + }, + { + "type": "paragraph", + "text": "Avoid creating custom window UI. System-provided windows look and behave in a way that people understand and recognize. Avoid making custom window frames or controls, and don’t try to replicate the system-provided appearance. Doing so without perfectly matching the system’s look and behavior can make your app feel broken." + }, + { + "type": "paragraph", + "text": "Use the term window in user-facing content. The system refers to app windows as windows regardless of type. Using different terms — including scene, which refers to window implementation — is likely to confuse people." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Not supported in iOS, tvOS, or watchOS." + } + ] + }, + { + "heading": "iPadOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Windows present in one of two ways depending on a person’s choice in Multitasking & Gestures settings." + }, + { + "type": "list", + "items": [ + "Full screen. App windows fill the entire screen, and people switch between them — or between multiple windows of the same app — using the app switcher.", + "Windowed. People can freely resize app windows. Multiple windows can be onscreen at once, and people can reposition them and bring them to the front. The system remembers window size and placement even when an app is closed." + ] + }, + { + "type": "paragraph", + "text": "Make sure window controls don’t overlap toolbar items. When windowed, app windows include window controls at the leading edge of the toolbar. If your app has toolbar buttons at the leading edge, they might be hidden by window controls when they appear. To prevent this, instead of placing buttons directly on the leading edge, move them inward when the window controls appear." + }, + { + "type": "paragraph", + "text": "Consider letting people use a gesture to open content in a new window. For example, people can use the pinch gesture to expand a Notes item into a new window. For developer guidance, see collectionView(_:sceneActivationConfigurationForItemAt:point:) (to transition from a collection view item), or UIWindowScene.ActivationInteraction (to transition from an item in any other view)." + }, + { + "type": "tip", + "text": "TipIf you only need to let people view one file, you can present it without creating your own window, but you must support multiple windows in your app. For developer guidance, see QLPreviewSceneActivationConfiguration." + } + ] + }, + { + "heading": "macOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In macOS, people typically run several apps at the same time, often viewing windows from multiple apps on one desktop and switching frequently between different windows — moving, resizing, minimizing, and revealing the windows to suit their work style." + }, + { + "type": "paragraph", + "text": "To learn about setting up a window to display your game in macOS, see Managing your game window for Metal in macOS." + } + ] + }, + { + "heading": "macOS window anatomy", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "A macOS window consists of a frame and a body area. People can move a window by dragging the frame and can often resize the window by dragging its edges." + }, + { + "type": "paragraph", + "text": "The frame of a window appears above the body area and can include window controls and a toolbar. In rare cases, a window can also display a bottom bar, which is a part of the frame that appears below body content." + } + ] + }, + { + "heading": "macOS window states", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "A macOS window can have one of three states:" + }, + { + "type": "list", + "items": [ + "Main. The frontmost window that people view is an app’s main window. There can be only one main window per app.", + "Key. Also called the active window, the key window accepts people’s input. There can be only one key window onscreen at a time. Although the front app’s main window is usually the key window, another window — such as a panel floating above the main window — might be key instead. People typically click a window to make it key; when people click an app’s Dock icon to bring all of that app’s windows forward, only the most recently accessed window becomes key.", + "Inactive. A window that’s not in the foreground is an inactive window." + ] + }, + { + "type": "paragraph", + "text": "The system gives main, key, and inactive windows different appearances to help people visually identify them. For example, the key window uses color in the title bar options for closing, minimizing, and zooming; inactive windows and main windows that aren’t key use gray in these options. Also, inactive windows don’t use vibrancy (an effect that can pull color into a window from the content underneath it), which makes them appear subdued and seem visually farther away than the main and key windows." + }, + { + "type": "note", + "text": "NoteSome windows — typically, panels like Colors or Fonts — become the key window only when people click the window’s title bar or a component that requires keyboard input, such as a text field." + }, + { + "type": "paragraph", + "text": "Make sure custom windows use the system-defined appearances. People rely on the visual differences between windows to help them identify the foreground window and know which window will accept their input. When you use system-provided components, a window’s background and button appearances update automatically when the window changes state; if you use custom implementations, you need to do this work yourself." + }, + { + "type": "paragraph", + "text": "Avoid putting critical information or actions in a bottom bar, because people often relocate a window in a way that hides its bottom edge. If you must include one, use it only to display a small amount of information directly related to a window’s contents or to a selected item within it. For example, Finder uses a bottom bar (called the status bar) to display the total number of items in a window, the number of selected items, and how much space is available on the disk. A bottom bar is small, so if you have more information to display, consider using an inspector, which typically presents information on the trailing side of a split view." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "visionOS defines two main window styles: default and volumetric. Both a default window (called a window) and a volumetric window (called a volume) can display 2D and 3D content, and people can view multiple windows and volumes at the same time in both the Shared Space and a Full Space." + }, + { + "type": "paragraph", + "text": "A window" + }, + { + "type": "paragraph", + "text": "A volume" + }, + { + "type": "note", + "text": "NotevisionOS also defines the plain window style, which is similar to the default style, except that the upright plane doesn’t use the glass background. For developer guidance, see PlainWindowStyle." + }, + { + "type": "paragraph", + "text": "The system defines the initial position of the first window or volume people open in your app or game. In both the Shared Space and a Full Space, people can move windows and volumes to new locations." + } + ] + }, + { + "heading": "visionOS windows", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "The default window style consists of an upright plane that uses an unmodifiable background material called glass and includes a close button, window bar, and resize controls that let people close, move, and resize the window. A window can also include a Share button, tab bar, toolbar, and one or more ornaments. By default, visionOS uses dynamic scale to help a window’s size appear to remain consistent regardless of its proximity to the viewer. For developer guidance, see DefaultWindowStyle." + }, + { + "type": "paragraph", + "text": "A window" + }, + { + "type": "paragraph", + "text": "Prefer using a window to present a familiar interface and to support familiar tasks. Help people feel at home in your app by displaying an interface they’re already comfortable with, reserving more immersive experiences for the meaningful content and activities you offer. If you want to showcase bounded 3D content like a game board, consider using a volume." + }, + { + "type": "paragraph", + "text": "Retain the window’s glass background. The default glass background helps your content feel like part of people’s surroundings while adapting dynamically to lighting and using specular reflections and shadows to communicate the window’s scale and position. Removing the glass material tends to cause UI elements and text to become less legible and to no longer appear related to each other; using an opaque background obscures people’s surroundings and can make a window feel constricting and heavy." + }, + { + "type": "paragraph", + "text": "Choose an initial window size that minimizes empty areas within it. By default, a window measures 1280x720 pt. When a window first opens, the system places it about two meters in front of the wearer, giving it an apparent width of about three meters. Too much empty space inside a window can make it look unnecessarily large while also obscuring other content in people’s space." + }, + { + "type": "paragraph", + "text": "Aim for an initial shape that suits a window’s content. For example, a default Keynote window is wide because slides are wide, whereas a default Safari window is tall because most webpages are much longer than they are wide. For games, a tower-building game is likely to open in a taller window than a driving game." + }, + { + "type": "paragraph", + "text": "Choose a minimum and maximum size for each window to help keep your content looking great. People appreciate being able to resize windows as they customize their space, but you need to make sure your layout adjusts well across all sizes. If you don’t set a minimum and maximum size for a window, people could make it so small that UI elements overlap or so large that your app or game becomes unusable. For developer guidance, see Positioning and sizing windows." + }, + { + "type": "paragraph", + "text": "A window containing 3D content" + }, + { + "type": "paragraph", + "text": "Minimize the depth of 3D content you display in a window. The system adds highlights and shadows to the views and controls within a window, giving them the appearance of depth and helping them feel more substantial, especially when people view the window from an angle. Although you can display 3D content in a window, the system clips it if the content extends too far from the window’s surface. To display 3D content that has greater depth, use a volume." + } + ] + }, + { + "heading": "visionOS volumes", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "You can use a volume to display 2D or 3D content that people can view from any angle. A volume includes window-management controls just like a window, but unlike in a window, a volume’s close button and window bar shift position to face the viewer as they move around the volume. For developer guidance, see VolumetricWindowStyle." + }, + { + "type": "paragraph", + "text": "A volume" + }, + { + "type": "paragraph", + "text": "Prefer using a volume to display rich, 3D content. In contrast, if you want to present a familiar, UI-centric interface, it generally works best to use a window." + }, + { + "type": "paragraph", + "text": "Place 2D content so it looks good from multiple angles. Because a person’s perspective changes as they move around a volume, the location of 2D content within it might appear to change in ways that don’t make sense. To pin 2D content to specific areas of 3D content inside a volume, you can use an attachment." + }, + { + "type": "paragraph", + "text": "In general, use dynamic scaling. Dynamic scaling helps a volume’s content remain comfortably legible and easy to interact with, even when it’s far away from the viewer. On the other hand, if you want a volume’s content to represent a real-world object, like a product in a retail app, you can use fixed scaling (this is the default)." + }, + { + "type": "paragraph", + "text": "Take advantage of the default baseplate appearance to help people discern the edges of a volume. In visionOS 2 and later, the system automatically makes a volume’s horizontal “floor,” or baseplate, visible by displaying a gentle glow around its border when people look at it. If your content doesn’t fill the volume, the system-provided glow can help people become aware of the volume’s edges, which can be particularly useful in keeping the resize control easy to find. On the other hand, if your content is full bleed or fills the volume’s bounds — or if you display a custom baseplate appearance — you may not want the default glow." + }, + { + "type": "paragraph", + "text": "Consider offering high-value content in an ornament. In visionOS 2 and later, a volume can include an ornament in addition to a toolbar and tab bar. You can use an ornament to reduce clutter in a volume and elevate important views or controls. When you use an attachment anchor to specify the ornament’s location, such as topBack or bottomFront, the ornament remains in the same position, relative to the viewer’s perspective, as they move around the volume. Be sure to avoid placing an ornament on the same edge as a toolbar or tab bar, and prefer creating only one additional ornament to avoid overshadowing the important content in your volume. For developer guidance, see ornament(visibility:attachmentAnchor:contentAlignment:ornament:)." + }, + { + "type": "paragraph", + "text": "Choose an alignment that supports the way people interact with your volume. As people move a volume, the baseplate can remain parallel to the floor of a person’s surroundings, or it can tilt to match the angle at which a person is looking. In general, a volume that remains parallel to the floor works well for content that people don’t interact with much, whereas a volume that tilts to match where a person is looking can keep content comfortably usable, even when the viewer is reclining." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Layout" + }, + { + "type": "paragraph", + "text": "Split views" + }, + { + "type": "paragraph", + "text": "Multitasking" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Windows — SwiftUI" + }, + { + "type": "paragraph", + "text": "WindowGroup — SwiftUI" + }, + { + "type": "paragraph", + "text": "UIWindow — UIKit" + }, + { + "type": "paragraph", + "text": "NSWindow — AppKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Added best practices, and updated with guidance for resizable windows in iPadOS." + ], + [ + "June 10, 2024", + "Updated to include guidance for using volumes in visionOS 2 and added game-specific examples." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Layout", + "url": "/design/human-interface-guidelines/layout" + }, + { + "title": "Spatial layout", + "url": "/design/human-interface-guidelines/spatial-layout" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/windows#Best-practices" + }, + { + "title": "Multitasking", + "url": "/design/human-interface-guidelines/multitasking" + }, + { + "title": "context menu", + "url": "/design/human-interface-guidelines/context-menus" + }, + { + "title": "File menu", + "url": "/design/human-interface-guidelines/the-menu-bar#File-menu" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/windows#Platform-considerations" + }, + { + "title": "iPadOS", + "url": "/design/human-interface-guidelines/windows#iPadOS" + }, + { + "title": "macOS", + "url": "/design/human-interface-guidelines/windows#macOS" + }, + { + "title": "macOS window anatomy", + "url": "/design/human-interface-guidelines/windows#macOS-window-anatomy" + }, + { + "title": "toolbar", + "url": "/design/human-interface-guidelines/toolbars" + }, + { + "title": "macOS window states", + "url": "/design/human-interface-guidelines/windows#macOS-window-states" + }, + { + "title": "vibrancy", + "url": "/design/human-interface-guidelines/materials" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/windows#visionOS" + }, + { + "title": "visionOS windows", + "url": "/design/human-interface-guidelines/windows#visionOS-windows" + }, + { + "title": "tab bar", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "ornaments", + "url": "/design/human-interface-guidelines/ornaments" + }, + { + "title": "scale", + "url": "/design/human-interface-guidelines/spatial-layout#Scale" + }, + { + "title": "immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "volume", + "url": "/design/human-interface-guidelines/windows#visionOS-volumes" + }, + { + "title": "depth", + "url": "/design/human-interface-guidelines/spatial-layout#Depth" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/windows#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/windows#Related" + }, + { + "title": "Split views", + "url": "/design/human-interface-guidelines/split-views" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/windows#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/windows#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/windows#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Workouts", + "url": "https://developer.apple.com/design/human-interface-guidelines/workouts", + "category": "patterns", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People can wear their Apple Watch during many types of workouts, and they might carry their iPhone or iPad during fitness activities like walking, wheelchair pushing, and running. In contrast, people tend to use their larger or more stationary devices like iPad Pro, Mac, and Apple TV to participate in live or recorded workout sessions by themselves or with others." + }, + { + "type": "paragraph", + "text": "You can create a workout experience for Apple Watch, iPhone, or iPad that helps people reach their goals by leveraging activity data from the device and using familiar components to display fitness metrics." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In a watchOS fitness app, use workout sessions to provide useful data and relevant controls. During a fitness app’s active workout sessions, watchOS continues to display the app as time passes between wrist raises, so it’s important to provide the workout data people are most likely to care about. For example, you might show elapsed or remaining time, calories burned, or distance traveled, and offer relevant controls like lap or interval markers." + }, + { + "type": "paragraph", + "text": "Avoid distracting people from a workout with information that’s not relevant. For example, people don’t need to review the list of workouts you offer or access other parts of your app while they’re working out. Here is an arrangement that many watchOS workout apps use, including Workout:" + }, + { + "type": "paragraph", + "text": "Large buttons that control the in-progress session — such as End, Resume, and New — appear on the leftmost screen." + }, + { + "type": "paragraph", + "text": "Metrics and other data appear on a dedicated screen that people can read at a glance." + }, + { + "type": "paragraph", + "text": "If supported, media playback controls appear on the rightmost screen." + }, + { + "type": "paragraph", + "text": "Use a distinct visual appearance to indicate an active workout. During a workout, people appreciate being able to recognize an active session at a glance. The metrics page can be a good way to show that a session is active because the values update in real time. In addition to displaying updating values, you can further distinguish the metrics screen by using a unique layout." + }, + { + "type": "paragraph", + "text": "Provide workout controls that are easy to find and tap. In addition to making it easy for people to pause, resume, and stop a workout, be sure to provide clear feedback that indicates when a session starts or stops." + }, + { + "type": "paragraph", + "text": "Help people understand the health information your app records if sensor data is unavailable during a workout. For example, water may prevent a heart-rate measurement, but your app can still record data like the distance people swam and the number of calories they burned. If your app supports the Swimming or Other workout types, explain the situation using language that’s similar to the language used in the system-provided Workout app, as shown below:" + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text from the Workout app" + ], + [ + "", + "GPS is not used during a Pool Swim, and water may prevent a heart-rate measurement, but Apple Watch will still track your calories, laps, and distance using the built-in accelerometer." + ], + [ + "", + "In this type of workout, you earn the calorie equivalent of a brisk walk anytime sensor readings are unavailable." + ], + [ + "", + "GPS will only provide distance when you do a freestyle stroke. Water might prevent a heart-rate measurement, but calories will still be tracked using the built-in accelerometer." + ] + ] + }, + { + "type": "paragraph", + "text": "Provide a summary at the end of a session. A summary screen confirms that a workout is finished and displays the recorded information. Consider enhancing the summary by including Activity rings, so that people can easily check their current progress." + }, + { + "type": "paragraph", + "text": "Discard extremely brief workout sessions. If a session ends a few seconds after it starts, either discard the data automatically or ask people if they want to record the data as a workout." + }, + { + "type": "paragraph", + "text": "Make sure text is legible for when people are in motion. When a session requires movement, use large font sizes, high-contrast colors, and arrange text so that the most important information is easy to read." + }, + { + "type": "paragraph", + "text": "Use Activity rings correctly. The Activity rings view is an Apple-designed element featuring one or more rings whose colors and meanings match those in the Activity app. Use them only for their documented purpose." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or watchOS. Not supported in macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Activity rings" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "WorkoutKit" + }, + { + "type": "paragraph", + "text": "Workouts and activity rings — HealthKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/workouts#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/workouts#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/workouts#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/workouts#Related" + }, + { + "title": "Activity rings", + "url": "/design/human-interface-guidelines/activity-rings" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/workouts#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/workouts#Videos" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/data/categories/technologies.json b/data/categories/technologies.json new file mode 100644 index 0000000..36c9e30 --- /dev/null +++ b/data/categories/technologies.json @@ -0,0 +1,12445 @@ +{ + "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": "technologies" + }, + "name": "Technologies", + "articles": [ + { + "title": "AirPlay", + "url": "https://developer.apple.com/design/human-interface-guidelines/airplay", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer the system-provided media player. The built-in media player offers a standard set of controls and supports features like chapter navigation, subtitles, closed captioning, and AirPlay streaming. It’s also easy to implement, provides a consistent and familiar playback experience across the system, and accommodates the needs of most media apps. Consider designing a custom video player only if the system-provided player doesn’t meet your app’s needs. For developer guidance, see AVPlayerViewController." + }, + { + "type": "paragraph", + "text": "Provide content in the highest possible resolution. Your HTTP Live Streaming (HLS) playlist needs to include the full range of available resolutions so that people can experience your content in the resolution that’s appropriate for the device they’re using (AVFoundation automatically selects the resolution based on the device). If you don’t include a range of resolutions, your content looks low quality when people stream it to a device that can play at higher resolutions. For example, content that looks great on iPhone at 720p will look low quality when people use AirPlay to stream it to a 4K TV." + }, + { + "type": "paragraph", + "text": "Stream only the content people expect. Avoid streaming content like background loops and short video experiences that make sense only within the context of the app itself. For developer guidance, see usesExternalPlaybackWhileExternalScreenIsActive." + }, + { + "type": "paragraph", + "text": "Support both AirPlay streaming and mirroring. Supporting both features gives people the most flexibility." + }, + { + "type": "paragraph", + "text": "Support remote control events. When you do, people can choose actions like play, pause, and fast forward on the lock screen, and through interaction with Siri or HomePod. For developer guidance, see Remote command center events." + }, + { + "type": "paragraph", + "text": "Don’t stop playback when your app enters the background or when the device locks. For example, people expect the TV show they started streaming from your app to continue while they check their mail or put their device to sleep. In this type of scenario, it’s also crucial to avoid automatic mirroring because people don’t want to stream other content on their device without explicitly choosing to do so." + }, + { + "type": "paragraph", + "text": "Don’t interrupt another app’s playback unless your app is starting to play immersive content. For example, if your app plays a video when it launches or auto-plays inline videos, play this content on only the local device, while allowing current playback to continue. For developer guidance, see ambient." + }, + { + "type": "paragraph", + "text": "Let people use other parts of your app during playback. When AirPlay is active, your app needs to remain functional. If people navigate away from the playback screen, make sure other in-app videos don’t begin playing and interrupt the streaming content." + }, + { + "type": "paragraph", + "text": "If necessary, provide a custom interface for controlling media playback. If you can’t use the system-provided media player, you can create a custom media player that gives people an intuitive way to enter AirPlay. If you need to do this, be sure to provide custom buttons that match the appearance and behavior of the system-provided ones, including distinct visual states that indicate when playback starts, is occurring, or is unavailable. Use only Apple-provided symbols in custom controls that initiate AirPlay, and position the AirPlay icon correctly in your custom player — that is, in the lower-right corner (in iOS 16 and iPadOS 16 and later)." + } + ] + }, + { + "heading": "Using AirPlay icons", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can download AirPlay icons in Resources. You have the following options for displaying the AirPlay icon in your app." + } + ] + }, + { + "heading": "Black AirPlay icon", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use the black AirPlay icon on white or light backgrounds when other technology icons also appear in black." + } + ] + }, + { + "heading": "White AirPlay icon", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use the white AirPlay icon on black or dark backgrounds when other technology icons also appear in white." + } + ] + }, + { + "heading": "Custom color AirPlay icon", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use a custom color when other technology icons also appear in the same color." + }, + { + "type": "paragraph", + "text": "Position the AirPlay icon consistently with other technology icons. If you display other technology icons within shapes, you can display the AirPlay icon in the same manner." + }, + { + "type": "paragraph", + "text": "Don’t use the AirPlay icon or name in custom buttons or interactive elements. Use the icon and the name AirPlay only in noninteractive ways." + }, + { + "type": "paragraph", + "text": "Pair the icon with the name AirPlay correctly. You can show the name below or beside the icon if you also reference other technologies in this way. Use the same font you use in the rest of your layout. Avoid using the AirPlay icon within text or as a replacement for the name AirPlay." + }, + { + "type": "paragraph", + "text": "Emphasize your app over AirPlay. Make references to AirPlay less prominent than your app name or main identity." + } + ] + }, + { + "heading": "Referring to AirPlay", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use correct capitalization when using the term AirPlay. AirPlay is one word, with an uppercase A and uppercase P, each followed by lowercase letters. If your layout displays only all-uppercase designations, you can typeset AirPlay in all uppercase to match the style of the rest of the layout." + }, + { + "type": "paragraph", + "text": "Always use AirPlay as a noun." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Use AirPlay to listen on your speaker" + ], + [ + "", + "AirPlay to your speaker" + ], + [ + "", + "You can AirPlay with [App Name]" + ] + ] + }, + { + "type": "paragraph", + "text": "Use terms like works with, use, supports, and compatible." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "[App Name] is compatible with AirPlay" + ], + [ + "", + "AirPlay-enabled speaker" + ], + [ + "", + "You can use AirPlay with [App Name]" + ], + [ + "", + "[App Name] has AirPlay" + ] + ] + }, + { + "type": "paragraph", + "text": "Use the name Apple with the name AirPlay if desired." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Compatible with Apple AirPlay" + ] + ] + }, + { + "type": "paragraph", + "text": "Refer to AirPlay if appropriate and to add clarity. If your content is specific to AirPlay, you can use Airplay to make that clear. You can also refer to AirPlay in technical specifications." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "[App Name] now supports AirPlay" + ] + ] + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS. Not supported in watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Design Resources" + }, + { + "type": "paragraph", + "text": "Apple Trademark List" + }, + { + "type": "paragraph", + "text": "Guidelines for Using Apple Trademarks and Copyrights" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "AVFoundation" + }, + { + "type": "paragraph", + "text": "AVKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/airplay#Best-practices" + }, + { + "title": "Using AirPlay icons", + "url": "/design/human-interface-guidelines/airplay#Using-AirPlay-icons" + }, + { + "title": "Black AirPlay icon", + "url": "/design/human-interface-guidelines/airplay#Black-AirPlay-icon" + }, + { + "title": "White AirPlay icon", + "url": "/design/human-interface-guidelines/airplay#White-AirPlay-icon" + }, + { + "title": "Custom color AirPlay icon", + "url": "/design/human-interface-guidelines/airplay#Custom-color-AirPlay-icon" + }, + { + "title": "Referring to AirPlay", + "url": "/design/human-interface-guidelines/airplay#Referring-to-AirPlay" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/airplay#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/airplay#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/airplay#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/airplay#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/airplay#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/airplay#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Always On", + "url": "https://developer.apple.com/design/human-interface-guidelines/always-on", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In the Always On state, a device can continue to give people useful, glanceable information in a low-power, privacy-preserving way by dimming the display and minimizing onscreen motion. The system can display different items depending on the device." + }, + { + "type": "list", + "items": [ + "On iPhone 14 Pro and iPhone 14 Pro Max, the system displays Lock Screen items like Widgets and Live Activities when people set aside their device face up and stop interacting with it.", + "When people drop their wrist while wearing Apple Watch, the system dims the watch face, continuing to display the interface of the app as long as it’s either frontmost or running a background session." + ] + }, + { + "type": "paragraph", + "text": "On both devices, the system displays notifications while in Always On, and people can tap the display to exit Always On and resume interactions." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Hide sensitive information. It’s crucial to redact personal information that people wouldn’t want casual observers to view, like bank balances or health data. You also need to hide personal information that might be visible in a notification; for guidance, see Notifications." + }, + { + "type": "paragraph", + "text": "Keep other types of personal information glanceable when it makes sense. On Apple Watch, for example, people typically appreciate getting pace and heart rate updates while they’re working out; on iPhone, people appreciate getting a glanceable update on a flight arrival or a notification when a ride-sharing service arrives. If people don’t want any information to be visible, they can turn off Always On." + }, + { + "type": "paragraph", + "text": "Keep important content legible and dim nonessential content. You can increase dimming on secondary text, images, and color fills to give more prominence to the information that’s important to people. For example, a to-do list app might remove row backgrounds and dim each item’s additional details to highlight its title. Also, if you display rich images or large areas of color, consider removing the images and using dimmed colors." + }, + { + "type": "paragraph", + "text": "Maintain a consistent layout. Avoid making distracting interface changes when Always On begins or ends and throughout the Always On experience. For example, when Always On begins, prefer transitioning an interactive component to an unavailable appearance — don’t just remove it. Within the Always On context, aim to make infrequent, subtle updates to the interface. For example, a sports app might pause granular play-by-play updates while in Always On, only updating the score when it changes. Note that unnecessary changes during Always On can be especially distracting on iPhone, because people often put their device face up on a surface, making motion on the screen visible even when they’re not looking directly at it." + }, + { + "type": "paragraph", + "text": "Gracefully transition motion to a resting state; don’t stop it instantly. Smoothly finishing the current motion helps communicate the transition and avoids making people think that something went wrong." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or watchOS. Not supported in iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Designing for watchOS" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Designing your app for the Always On state — watchOS apps" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Updated intro image artwork." + ], + [ + "September 23, 2022", + "Expanded guidance to cover the Always On display on iPhone 14 Pro and iPhone 14 Pro Max." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Widgets", + "url": "/design/human-interface-guidelines/widgets" + }, + { + "title": "Live Activities", + "url": "/design/human-interface-guidelines/live-activities" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/always-on#Best-practices" + }, + { + "title": "Notifications", + "url": "/design/human-interface-guidelines/notifications" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/always-on#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/always-on#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/always-on#Related" + }, + { + "title": "Designing for watchOS", + "url": "/design/human-interface-guidelines/designing-for-watchos" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/always-on#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/always-on#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/always-on#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "App Clips", + "url": "https://developer.apple.com/design/human-interface-guidelines/app-clips", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "App Clips deliver an experience from your app or game without requiring people to download the full app from the App Store. App Clips focus on a fast solution to a task or contain a demo that showcases the full app or game, and they remain on the device for a limited amount of time while preserving people’s privacy." + }, + { + "type": "paragraph", + "text": "People discover and launch App Clips in a variety of situations and contexts. At a physical location, people launch an App Clip by scanning an App Clip Code, NFC tag, or a QR code. An App Clip Code tends to be the best way for people to discover and launch your App Clip because its distinct design is immediately recognizable, and people trust it to offer a fast, secure way to launch an App Clip." + }, + { + "type": "paragraph", + "text": "On their device, people launch an App Clip from location-based suggestions they permit in Siri Suggestions, the Maps app, Smart App Banners on websites, App Clip cards in Safari, and by tapping links others share with them in the Messages app. Starting with iOS 17, an app can include links and App Clip previews that people tap to launch another app’s App Clip." + }, + { + "type": "paragraph", + "text": "Consider creating an App Clip if your app provides an in-the-moment experience that helps people perform a task over a finite amount of time. For example:" + }, + { + "type": "list", + "items": [ + "A rental bike could come with an App Clip Code that people tap or scan to launch an App Clip that lets them rent the bike.", + "A coffee shop could offer an App Clip for fast advance orders that customers launch from a Smart App Banner or an App Clip card on the shop’s website. Customers could share a link to the website from the Messages app, which recipients then tap to launch the App Clip from within Messages.", + "A food truck could create marketing material (for example, a poster to promote a seasonal dish) that includes an App Clip Code. People can scan the App Clip Code with the Camera app on their device and instantly launch the App Clip to order the seasonal dish.", + "A restaurant could let diners pay for a meal by launching an App Clip from the Maps app or a suggestion from Siri Suggestions, or by holding their device close to an App Clip Code or NFC tag at their table.", + "A museum could have visitors scan App Clip Codes or QR codes on labels next to displayed works to launch an App Clip that reveals augmented reality content or provides audio commentary." + ] + }, + { + "type": "paragraph", + "text": "Consider creating an App Clip to let people experience your app or game before committing to a purchase or subscription. Focus on providing people with an opportunity to experience and understand your app or game. For example:" + }, + { + "type": "list", + "items": [ + "A game might offer an App Clip that lets people play a demo version of the game, including a tutorial and the first level of the game.", + "A fitness app might offer an App Clip with a free workout and a guided meditation.", + "A text editor might allow people to create and save a document using the demo App Clip." + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see App Clips." + } + ] + }, + { + "heading": "Designing your App Clip", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Allow people to complete a task or a demo in your App Clip. Don’t require people to install the full app to experience the entire demo, to complete a task, or to finish a level in a game." + }, + { + "type": "paragraph", + "text": "Focus on essential features. Interactions with App Clips are quick and focused. Limit features to what’s necessary to accomplish the task at hand. Reserve advanced or complex features for the app. If you offer a demo version of your full app, focus on essential features that give people a good sense of your game or your app’s functionality." + }, + { + "type": "paragraph", + "text": "Don’t use App Clips solely for marketing purposes. App Clips need to provide real value and help people accomplish tasks. Don’t use them as a means to advertise services or products, and don’t display ads in your App Clip." + }, + { + "type": "paragraph", + "text": "Avoid using web views in your App Clip. App Clips use native components and frameworks to offer an app-quality experience. If only web components are available to you, offer a quick link to your website instead of an App Clip." + }, + { + "type": "paragraph", + "text": "Design a linear, easy-to-use, and focused user interface. App Clips don’t need tab bars, complex navigation, or settings. Keep the number of screens and entry forms to a minimum. Remove extraneous information and reduce complexity in the user interface wherever possible." + }, + { + "type": "paragraph", + "text": "On launch, show the most relevant part of your App Clip. Skip unnecessary steps and take people immediately to the part of the App Clip that best fits their context." + }, + { + "type": "paragraph", + "text": "Ensure people can use your App Clip immediately. App Clips need to include all required assets, omit splash screens, and never make people wait on launch." + }, + { + "type": "paragraph", + "text": "Ensure your App Clip is small. The smaller your App Clip, the faster it will launch on a person’s device. Keeping your App Clip small is especially important when bandwidth is limited. As much as possible, reduce unnecessary code and remove unused assets. Avoid downloading additional data, which can take away the feeling of immediacy." + }, + { + "type": "paragraph", + "text": "Make the App Clip shareable. When someone shares a link to an App Clip in the Messages app, recipients can launch the App Clip from within the Messages app. Offer the ability to share links to specific points in your App Clip, and encourage people to share the App Clip with others." + }, + { + "type": "paragraph", + "text": "Make it easy to pay for a service or product. Entering payment information can be a long and error-prone task. Consider supporting Apple Pay to offer express checkout and let people enter shipping information with no typing." + }, + { + "type": "paragraph", + "text": "Avoid requiring people to create an account before they can benefit from your App Clip. Creating an account is a complex task that takes time and effort. Consider not requiring an account, or think about asking people to create an account after they finish a task. If your App Clip requires an account to provide value, limit the amount of information people need to provide — for example, by offering Sign in with Apple." + }, + { + "type": "paragraph", + "text": "Provide a familiar, focused experience in your app. When people install the full app, it replaces the App Clip on their device. From this moment, invocations that would have launched the App Clip launch the full app instead. Ensure your app provides a focused, familiar experience to people who previously used the App Clip. Don’t require additional steps that slow people down; for example, don’t require people to log in again when they transition from the App Clip to the app." + } + ] + }, + { + "heading": "Preserving privacy", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The system imposes limits on App Clips to ensure people’s privacy. For example, App Clips can’t perform background operations. For developer guidance, see Choosing the right functionality for your App Clip." + }, + { + "type": "paragraph", + "text": "Limit the amount of data you store and handle yourself. If you need to store people’s data — for example, login information — store it securely. In addition, don’t rely on the availability of data you previously stored on the device — the system may have removed the App Clip from the device between launches and deleted all of its data. If you store login information, securely store it off the device." + }, + { + "type": "paragraph", + "text": "Consider offering Sign in with Apple. Sign in with Apple securely retains login information off people’s devices and preserves their privacy. For guidance, see Sign in with Apple." + }, + { + "type": "paragraph", + "text": "Offer a secure way to pay for services or goods that also respects people’s privacy. For example, consider offering Apple Pay." + } + ] + }, + { + "heading": "Showcasing your app", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People don’t manage App Clips themselves, and App Clips don’t appear on the Home screen. Instead, the system removes an App Clip after a period of inactivity." + }, + { + "type": "paragraph", + "text": "Because apps remain the best way to keep people engaged over time, the system helps them discover and install the full app:" + }, + { + "type": "list", + "items": [ + "On the App Clip card, people can either launch the App Clip or visit the full app’s page on the App Store.", + "When people first launch the App Clip, the system displays an app banner at the top of the screen. Like the App Clip card, the banner allows people to visit the app’s page on the App Store." + ] + }, + { + "type": "paragraph", + "text": "In addition, you can display an overlay in your App Clip that allows people to download the full app from within the App Clip." + }, + { + "type": "paragraph", + "text": "Don’t compromise the user experience by asking people to install the full app. If your App Clip offers an on-the-go experience, consider whether the App Clip card and the system-provided app banner provide enough incentive for people to download the full app. If your App Clip offers a demo experience, let people fully experience the demo before asking them to install the full app." + }, + { + "type": "paragraph", + "text": "Pick the right time to recommend your app. When someone completes a task or reaches a natural pause, display an SKOverlay that allows people to initiate a download of your full app or game from the context of the App Clip." + }, + { + "type": "paragraph", + "text": "Recommend your app in a nonintrusive, polite way. Don’t ask people to install the full app repeatedly or interrupt them during a task. Push notifications aren’t a good way to ask people to install the app either. Clearly communicate your app’s additional features." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Recommending your app to App Clip users." + } + ] + }, + { + "heading": "Limiting notifications", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "App Clips provide the option to schedule and receive notifications for up to 8 hours after launch, enough time to follow up and complete most common tasks." + }, + { + "type": "paragraph", + "text": "Only ask for permission to use notifications for an extended period of time if it’s really needed. If your App Clip’s functionality spans more than a day, explicitly request permission to schedule and receive notifications. For example, a car rental company’s App Clip can ask for permission to send a notification that reminds people that they need to return a rented car soon." + }, + { + "type": "paragraph", + "text": "Keep notifications focused. Don’t send purely promotional notifications, and only use notifications in response to an explicit user action. If a person completes their task without leaving the App Clip, you might not need to send any notifications at all." + }, + { + "type": "paragraph", + "text": "Use notifications to help people complete a task. Notifications for an App Clip relate directly to the task the App Clip helps to accomplish. For example, an App Clip that helps people order food could send notifications related to a scheduled delivery." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Enabling notifications in App Clips." + } + ] + }, + { + "heading": "Creating App Clips for businesses", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If you’re a platform provider who services businesses, you may create several App Clip experiences in App Store Connect and use a single App Clip to power them all. To people using the App Clip, it appears with the branding of an individual business or location instead of your own branding." + }, + { + "type": "paragraph", + "text": "Use consistent branding. When people see the App Clip card for a business, the brand for that business is front and center. Tone down your own branding and make sure the branding for the business is clearly visible to avoid confusing people when they enter the App Clip experience." + }, + { + "type": "paragraph", + "text": "Consider multiple businesses. An App Clip may power many different businesses or a business that has multiple locations. In both scenarios, people may end up using the App Clip for more than one business or location at a time. The App Clip must handle this use case and update its user interface accordingly. For example, consider a way to switch between recent businesses or locations within your App Clip, and verify a person’s location when they launch it." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Configuring App Clip experiences." + } + ] + }, + { + "heading": "Creating content for an App Clip card", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The system-provided App Clip card is people’s first interaction with your App Clip, so give careful consideration to its images and copy." + }, + { + "type": "paragraph", + "text": "Be informative. Make sure the image on the App Clip card clearly communicates the features offered by your App Clip, supported tasks, or content." + }, + { + "type": "paragraph", + "text": "Prefer photography and graphics. Avoid using a screenshot of your app’s user interface because it’s unlikely to communicate the purpose of your App Clip. Instead, use an image that helps people understand the App Clip’s value, or a photo of the location of its associated business or point of interest." + }, + { + "type": "paragraph", + "text": "Avoid using text. Text in the header image isn’t localizable, can be difficult to read, and can make a card image less aesthetically pleasing." + }, + { + "type": "paragraph", + "text": "Adhere to image requirements. Use a 1800x1200 px PNG or JPEG image without transparency." + }, + { + "type": "paragraph", + "text": "Use concise copy. An App Clip card requires both a title and a subtitle. Clearly express the purpose of your App Clip within the available space so people can read and understand it at a glance. Create a title that has no more than 30 characters and a subtitle that has no more than 56 characters." + }, + { + "type": "paragraph", + "text": "Pick a verb for the action button that best fits your App Clip. Possible verbs are View, Play, or Open. Pick View for media, or if your App Clip provides informational or educational content. Pick Play for games. Choose Open for all other App Clips." + } + ] + }, + { + "heading": "App Clip Codes", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "App Clip Codes are the best way for people to discover your App Clip. Their distinct design is immediately recognizable, and they offer a fast, secure way to launch your App Clip." + }, + { + "type": "paragraph", + "text": "App Clip Code with the App Clip logo" + }, + { + "type": "paragraph", + "text": "App Clip Code without the App Clip logo" + }, + { + "type": "paragraph", + "text": "App Clip Codes always use the designs Apple provides and follow size, placement, and printing guidelines. Choose between the badge design that uses the App Clip logo ( App Clip) or, when space is at a premium, a design without it. Create App Clip Codes that use a default color pair, or choose custom foreground and background colors. For developer guidance, see Creating App Clip Codes." + } + ] + }, + { + "heading": "Interacting with App Clip Codes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "App Clip Codes come in two variants: scan-only or with an embedded NFC tag (NFC-integrated)." + }, + { + "type": "paragraph", + "text": "The scan-only variant uses a camera icon in its center to let people know to use the Camera app or the Code Scanner in Control Center to scan the App Clip Code. The NFC-integrated variant uses an iPhone icon at its center that guides people to hold their device close to the App Clip Code or to scan it using the NFC Tag Reader in Control Center. People can also scan an NFC-integrated App Clip Code with the Camera app or the Code Scanner in Control Center. For example:" + }, + { + "type": "list", + "items": [ + "A coffee shop could place an App Clip Code on their menu. A guest could hold their device close to the App Clip Code and instantly launch the shop’s App Clip to order a drink.", + "A gas station could have an NFC-integrated App Clip Code attached to each pump. A traveler could hold their device close to it to launch the gas station’s App Clip and use it to pay for their refill.", + "A video game creator could hand out marketing material at an industry event that includes an App Clip Code. An event attendee could scan the code to launch an App Clip that’s a playable demo of their latest video game." + ] + } + ] + }, + { + "heading": "Displaying App Clip Codes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When you start designing your App Clip Codes, choose the variant that works best for the way people use your App Clip. If people can physically access the App Clip Code, use the NFC-integrated variant. For example:" + }, + { + "type": "list", + "items": [ + "On a tabletop at a restaurant", + "Near a register at a retail store", + "In a storefront window", + "On signage", + "On a gift card or coupon" + ] + }, + { + "type": "paragraph", + "text": "If you need to place your App Clip Code in an area that’s physically inaccessible or you need to display it digitally, use a scan-only App Clip Code. For example:" + }, + { + "type": "list", + "items": [ + "On posters or printed advertising", + "On signage behind a counter or unreachable in a storefront", + "On digital materials such as digital displays, in emails, or on images you post to social media" + ] + }, + { + "type": "paragraph", + "text": "No matter which of the two variants you use, it’s important you carefully consider where you place your App Clip Code to ensure a reliable scanning experience." + }, + { + "type": "paragraph", + "text": "Include the App Clip logo when space allows. The logo helps make it clear that the code launches an App Clip; however, if you can’t meet the clear space requirements, use the App Clip Code design without the App Clip logo. Also, use the design without the App Clip logo if you place the App Clip Code on disposable paper or plastic items, or on items associated with gambling or drinking. For example, use the App Clip Code without the App Clip logo on playing cards, poker chips, or bar coasters. The App Clip logo is always part of the badge design where it appears below the App Clip Code; never use the App Clip logo on its own." + }, + { + "type": "paragraph", + "text": "Place your App Clip Code on a flat or cylindrical surface only. If you place your App Clip Code on a cylindrical surface — for example, on a scooter’s handlebar — make sure the width of the App Clip Code doesn’t exceed one-sixth of the cylinder’s circumference." + }, + { + "type": "paragraph", + "text": "Help your App Clip Code remain as flat as possible so it’s easy for people to scan. To provide the best scanning experience, avoid displaying App Clip Codes on deformable materials that readily fold or crumple, such as paper, plastic, or fabric. If you need to make your App Clip Code available on a bag, flexible box, or other deformable object, display it on something rigid — like a card — that you attach to the object. If you create an App Clip Code sticker, make sure it adheres well to flat surfaces." + }, + { + "type": "paragraph", + "text": "Place your App Clip Code in a location that helps ensure reliable scanning. For example, place a scan-only App Clip Code in a location that offers enough light to ensure reliable scanning, and don’t require people to scan from a wide angle." + }, + { + "type": "paragraph", + "text": "Make sure the App Clip Code is unobstructed. Don’t overlay the App Clip Code with text, logos, or images. Never animate the App Clip Code or dim it." + }, + { + "type": "paragraph", + "text": "Display the App Clip Code in an upright position. Don’t rotate the generated App Clip Code or display the center glyph at an angle." + }, + { + "type": "paragraph", + "text": "Don’t create App Clip Codes that are too small. App Clip Codes must adhere to the following specifications." + }, + { + "type": "table", + "rows": [ + [ + "Type", + "Minimum size" + ], + [ + "Printed communications", + "Minimum diameter of 3/4 inch (1.9 cm)." + ], + [ + "Digital communications", + "Minimum size of 256×256 px. Use a PNG or SVG file." + ], + [ + "NFC-integrated App Clip Code", + "The embedded NFC tag needs to be at least 35 mm in diameter or of equivalent size. For example, if your embedded NFC tag is 35 mm in diameter, your printed App Clip Code needs to be at least 1.37 inches (3.48 cm) in diameter." + ] + ] + }, + { + "type": "paragraph", + "text": "When determining the dimensions of your App Clip Codes, consider a distance to code size ratio of no more than 20:1. If possible, use a ratio of 10:1 to ensure reliable scanning. For example, an App Clip that people scan from 40 inches (101 cm) away needs to be at least 4 inches (10.16 cm) in diameter." + }, + { + "type": "paragraph", + "text": "If you display an App Clip Code near a QR Code or other scannable item, choose a size for the App Clip Code that’s at least the other code’s or item’s size." + }, + { + "type": "paragraph", + "text": "Provide enough space between an App Clip Code and adjacent App Clip Codes, graphics, or materials. The minimum clear space around an App Clip Code is equal to the space between the center glyph and the circular code. If you place your App Clip Code next to another App Clip Code or other machine-readable code, leave enough clear space to allow for reliable scanning of each code." + } + ] + }, + { + "heading": "Using clear messaging", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Add clear messaging that informs people how they can use the App Clip Code to launch your App Clip, especially if you use the design without the App Clip logo. For example, add a call to action next to an App Clip Code you display in an email or on a poster. Use the suggested call-to-action messaging or your own copy. Always use a simple, clear call to action." + }, + { + "type": "paragraph", + "text": "For a scan-only App Clip Code, you can use the following call to action:" + }, + { + "type": "list", + "items": [ + "Scan to [describe what people can do with your App Clip].", + "Scan using the camera on your iPhone or iPad to [describe what people can do with your App Clip]." + ] + }, + { + "type": "paragraph", + "text": "For an NFC-integrated App Clip Code, you can use the following call to action:" + }, + { + "type": "list", + "items": [ + "Scan to [describe what people can do with your App Clip].", + "Hold your iPhone near the [object name] to launch an App Clip that [describe what a person can do with your App Clip]." + ] + }, + { + "type": "paragraph", + "text": "For more information, see NFC." + }, + { + "type": "paragraph", + "text": "Adhere to Guidelines for Using Apple Trademarks when referring to your App Clip and App Clip Codes. For example, Apple trademarks can’t appear in your app name or images, always use title case when using the terms App Clips or App Clip Code, and so on. For additional information, see Legal requirements." + } + ] + }, + { + "heading": "Customizing your App Clip Code", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use App Store Connect or the App Clip Code Generator command-line tool to create App Clip Codes, and follow best practices to ensure a reliable scanning experience." + }, + { + "type": "paragraph", + "text": "Always use the generated App Clip Code. Don’t create your own App Clip Code design or modify a generated App Clip Code in any way. Don’t apply filters, augment its colors, or add glows, shadows, gradients, or reflections. They negatively impact people’s scanning experience. When scaling a generated App Clip Code, don’t change the generated code’s aspect ratio, and be sure to scale all attributes of the App Clip Code — for example the stroke widths." + }, + { + "type": "paragraph", + "text": "Choose colors with enough contrast that ensure accurate scanning. Each App Clip Code uses three colors: a foreground color, a background color, and a third color that’s generated for you based on the foreground and background colors. Both App Store Connect and the App Clip Code Generator command-line tool offer a selection of default color pairs. Alternatively, you can choose custom foreground and background colors. Note that you can’t choose custom colors that will lead to a suboptimal scanning experience. If your color selection doesn’t work well, neither App Store Connect nor the command-line tool will generate an App Clip Code. To help you choose a color combination that works well, both tools contain functionality to suggest a different foreground color based on your custom background color. For more information, see Creating App Clip Codes with the App Clip Code Generator and Creating App Clip Codes with App Store Connect." + } + ] + }, + { + "heading": "Printing guidelines", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "App Clip Codes offer the best experience to launch App Clips. As a result, it’s important to manufacture and display App Clip Codes that offer a reliable scanning experience for a long time. You can print App Clip Codes yourself, or work with a professional printing service — for example, RR Donnelley." + }, + { + "type": "paragraph", + "text": "Always test printed App Clip Codes before you distribute them to be sure they’re scannable from a variety of angles." + }, + { + "type": "paragraph", + "text": "Use high-quality, non-textured print materials. Print App Clip Codes on matte finishes. Avoid shine, gloss, reflective or holographic overlays, as well as thin laminate finishes or materials. In case you need to laminate print material with an App Clip Code on it, use a matte laminate to avoid shine and reflections. If you place your App Clip Code outdoors, use UV-resistant materials or coatings to prevent fading from exposure to sunlight, rain, and other weather conditions. If you work with a professional printing service, use flexographic printing for best results. If you print the App Clip Codes yourself using a desktop printer, use an inkjet printer for best results." + }, + { + "type": "paragraph", + "text": "Use high-resolution images and printer settings. When rasterizing the SVG file, set the image resolution to at least 600 ppi, and print your App Clip Codes with a minimum resolution of 300 dpi. Consider leveling and calibrating your printer before printing to ensure a high print quality, and avoid poor color channel alignment, inaccurate gamma values, artifacts, or printing elliptical or otherwise distorted App Clip Codes. When using receipt printers, print App Clip Codes as close to the paper’s maximum bounds as possible." + }, + { + "type": "paragraph", + "text": "Use correct color settings when you convert the generated SVG file to a CMYK image. Both the App Clip Code Generator command-line tool and App Store Connect generate App Clip Codes as SVG files in the sRGB color space. To print colors that match the SVG file, convert the sRGB image to a CMYK image. Use a relative calorimetric (media-relative) intent when performing the conversion. Use “Generic CMYK ICC profile” on CMYK printers or “Gracol 2013 ICC profile” on CMYKOV printers and allow for a color tolerance CIELab Delta E of 2.5." + }, + { + "type": "paragraph", + "text": "If you’re using a printer that only prints in grayscale, only generate grayscale App Clip Codes. Codes generated in color and then printed in grayscale may work less reliably." + }, + { + "type": "paragraph", + "text": "For NFC-integrated App Clip Codes, choose Type 5 NFC tags. The embedded NFC tag needs to be at least 35 mm in diameter or of equivalent size." + }, + { + "type": "paragraph", + "text": "If you create large batches of App Clip Codes, thoroughly test your printing workflow, and verify printed App Clip Codes. For example, conduct small, inexpensive print runs using a subset of codes. Print your App Clip Codes on print templates with additional padded regions that allow you to display the encoded invocation URL and the SVG filename alongside each code for validation at the time of print." + }, + { + "type": "paragraph", + "text": "If you create many App Clip Codes with the App Clip Code Generator tool or App Store Connect, you’ll likely work with a professional printing service. If this is the case, you need to handle a lot of SVG files. Because you have no way of knowing which App Clip Code encodes which URL by looking at an App Clip Code, you need to use a file that contains information about which SVG file maps to which invocation URL. Under any circumstance, careful file management, versioning, and change tracking are key to avoiding faulty print runs. For more information, see Preparing multiple App Clip Codes for production." + } + ] + }, + { + "heading": "Verifying your printer’s calibration", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A reliable scanning experience depends on the quality of your printed App Clip Codes. To ensure printing App Clip Codes results in a reliable scanning experience and to avoid using a printer that can’t print high-quality App Clip Codes, Apple offers printer calibration test sheets you can use to verify your printer’s settings and print quality." + }, + { + "type": "paragraph", + "text": "Verify print quality of your chosen color pair with the printer calibration test sheet that shows text boxes for each default color pair. Follow the instructions on the sheet to print it at the right scale and to verify that your printer can create high-quality App Clip Codes." + }, + { + "type": "paragraph", + "text": "Verify your printer’s grayscale settings by printing the printer calibration test sheet that shows two grayscale bars. If any of the specific gray colors are light or entirely missing, the printer may need calibration or may not be suitable for printing an App Clip Code that allows for reliable scanning." + } + ] + }, + { + "heading": "Legal requirements", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Only the Apple-provided App Clip Codes created in App Store Connect or with the App Clip Code Generator command-line tool and that follow these guidelines are approved for use." + }, + { + "type": "paragraph", + "text": "App Clip Codes are approved for use to indicate availability of an App Clip. Apple may update the App Clip Code design from time to time at Apple’s discretion." + }, + { + "type": "paragraph", + "text": "In the event your App Clip is no longer active, also stop displaying the App Clip Code associated with that inactive App Clip." + }, + { + "type": "paragraph", + "text": "You may not use the App Clip Code (including, without limitation, the Apple Logo, the App Clip mark, and the App Clip Code designs) as part of your own company name or as part of your product name. You may not seek copyright or trademark registration for the App Clip Codes or any elements contained therein." + }, + { + "type": "paragraph", + "text": "The App Clip Codes described in these guidelines must not be used in any manner that is likely to reduce, diminish, or damage the goodwill, value, or reputation associated with Apple or App Clips; or that infringes or violates the trademarks or other proprietary rights of any third party; or that is likely to cause confusion as to the source of products or services." + }, + { + "type": "paragraph", + "text": "Apple retains all rights to its trademarks, copyrights, or other intellectual property rights contained in the materials provided for use hereunder, including, without limitation, the App Clip Codes and any elements contained therein." + }, + { + "type": "paragraph", + "text": "Don’t add a symbol to App Clip Codes created in App Store Connect or with the App Clip Code Generator command-line tool." + }, + { + "type": "paragraph", + "text": "Don’t translate any Apple trademark. Apple trademarks must remain in English even when they appear within text in a language other than English. With Apple’s approval, a translation of the legal notice and credit lines (but not the trademarks) can be used in materials distributed outside the U.S." + }, + { + "type": "paragraph", + "text": "For more information about using Apple trademarks, see Guidelines for Using Apple Trademarks." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Pay" + }, + { + "type": "paragraph", + "text": "Sign in with Apple" + }, + { + "type": "paragraph", + "text": "Guidelines for Using Apple Trademarks and Copyrights" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "App Clips" + }, + { + "type": "paragraph", + "text": "App Store Connect" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Updated guidance to include demo App Clips." + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Designing your App Clip", + "url": "/design/human-interface-guidelines/app-clips#Designing-your-App-Clip" + }, + { + "title": "Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay" + }, + { + "title": "Sign in with Apple", + "url": "/design/human-interface-guidelines/sign-in-with-apple" + }, + { + "title": "Preserving privacy", + "url": "/design/human-interface-guidelines/app-clips#Preserving-privacy" + }, + { + "title": "Showcasing your app", + "url": "/design/human-interface-guidelines/app-clips#Showcasing-your-app" + }, + { + "title": "Limiting notifications", + "url": "/design/human-interface-guidelines/app-clips#Limiting-notifications" + }, + { + "title": "Creating App Clips for businesses", + "url": "/design/human-interface-guidelines/app-clips#Creating-App-Clips-for-businesses" + }, + { + "title": "Creating content for an App Clip card", + "url": "/design/human-interface-guidelines/app-clips#Creating-content-for-an-App-Clip-card" + }, + { + "title": "App Clip Codes", + "url": "/design/human-interface-guidelines/app-clips#App-Clip-Codes" + }, + { + "title": "Interacting with App Clip Codes", + "url": "/design/human-interface-guidelines/app-clips#Interacting-with-App-Clip-Codes" + }, + { + "title": "Displaying App Clip Codes", + "url": "/design/human-interface-guidelines/app-clips#Displaying-App-Clip-Codes" + }, + { + "title": "Using clear messaging", + "url": "/design/human-interface-guidelines/app-clips#Using-clear-messaging" + }, + { + "title": "NFC", + "url": "/design/human-interface-guidelines/nfc" + }, + { + "title": "Legal requirements", + "url": "/design/human-interface-guidelines/app-clips#Legal-requirements" + }, + { + "title": "Customizing your App Clip Code", + "url": "/design/human-interface-guidelines/app-clips#Customizing-your-App-Clip-Code" + }, + { + "title": "Printing guidelines", + "url": "/design/human-interface-guidelines/app-clips#Printing-guidelines" + }, + { + "title": "Verifying your printer’s calibration", + "url": "/design/human-interface-guidelines/app-clips#Verifying-your-printers-calibration" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/app-clips#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/app-clips#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/app-clips#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/app-clips#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/app-clips#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/app-clips#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Apple Pay", + "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pay", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People authorize payments and provide shipping and contact information, using credentials that are securely stored on the device." + }, + { + "type": "tip", + "text": "TipIt’s important to understand the difference between Apple Pay and In-app purchase. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and tickets for events; and for donations. Use In-App Purchase in your app to sell virtual goods, such as premium content for your app, and subscriptions for digital content." + }, + { + "type": "paragraph", + "text": "Apps and websites that accept Apple Pay display it as an available payment option, and include an Apple Pay button in the purchasing flow that people tap to bring up a payment sheet. During checkout, the payment sheet can show the credit or debit card linked to Apple Pay, purchase amount (including tax and fees), shipping options, and contact information. People make any necessary adjustments and then authorize payment and complete the purchase. For developer guidance, see Apple Pay." + }, + { + "type": "paragraph", + "text": "All websites that offer Apple Pay must include a privacy statement and adhere to the Acceptable use guidelines for Apple Pay on the web. For developer guidance, see Apple Pay on the Web. For a hands-on demo of Apple Pay on the web, see Apple Pay on the web interactive demo." + }, + { + "type": "paragraph", + "text": "The device performs payment authentication in most cases where the device supports Face ID, Touch ID, or Optic ID. In some cases, the system transfers payment authentication to a nearby iPhone, iPad, or Apple Watch via a secure Bluetooth connection or a scannable code." + } + ] + }, + { + "heading": "Offering Apple Pay", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Offer Apple Pay on all devices and browsers that support it. If the device doesn’t support Apple Pay, don’t present Apple Pay as a payment option. Use Apple Pay APIs to evaluate when a device can support Apple Pay. For developer guidance, see PKPaymentAuthorizationController (iOS, watchOS) and canMakePayments (web)." + }, + { + "type": "paragraph", + "text": "If you use Apple Pay APIs to find out whether someone has an active card in Wallet, you must make Apple Pay the primary — but not necessarily sole — payment option everywhere you use the APIs. For example, you might pre-select Apple Pay as the payment option when you display it alongside other options. For developer guidance, see Offering Apple Pay in Your App (iOS, watchOS) and Checking for Apple Pay availability (web)." + }, + { + "type": "paragraph", + "text": "If you also offer other payment methods, offer Apple Pay at the same time. Feature Apple Pay at least as prominently as the other options on every page or screen that offers or accepts payment methods." + }, + { + "type": "paragraph", + "text": "If you use an Apple Pay button to start the Apple Pay payment process, you must use the Apple-provided API to display it. Unlike a button graphic, the buttons produced by the API always have the correct appearance and are localized automatically." + }, + { + "type": "paragraph", + "text": "If you use a custom button to start the Apple Pay payment process, make sure your custom button doesn’t display “Apple Pay” or the Apple Pay logo. In this scenario, you must let people know that you accept Apple Pay by displaying the Apple Pay mark or referencing Apple Pay in text on the same page that displays your payment button." + }, + { + "type": "paragraph", + "text": "Use Apple Pay buttons only to start the Apple Pay payment process and, when appropriate, the Apple Pay set-up process. When people choose an Apple Pay button to make a purchase, but their device doesn’t have Apple Pay set up, they’re given the opportunity to set up Apple Pay. Don’t use Apple Pay buttons in any other ways." + }, + { + "type": "paragraph", + "text": "Don’t hide an Apple Pay button or make it appear unavailable. If an Apple Pay button can’t be used yet, such as when a product size or color hasn’t been selected, gracefully point out the problem after someone taps or clicks the button." + }, + { + "type": "paragraph", + "text": "Use the Apple Pay mark only to communicate that Apple Pay is accepted. The Apple Pay mark doesn’t facilitate payment. Never use it as a payment button or position it as a button. When using the Apple Pay mark to indicate Apple Pay as the selected payment method, you can create a separate custom button conforming to your app’s design to initiate the Apple Pay payment." + }, + { + "type": "paragraph", + "text": "Inform search engines that Apple Pay is accepted on your website. If your website uses semantic markup to provide product details to search engines, list Apple Pay as a payment option." + }, + { + "type": "paragraph", + "text": "For app developer guidance, see Apple Pay. For website developer guidance, including how to determine whether Apple Pay on the web is available, see Apple Pay on the Web." + } + ] + }, + { + "heading": "Streamlining checkout", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Provide a cohesive checkout experience. It’s best when the entire checkout flow feels tightly integrated with your app or website. To strengthen people’s perception of integration, use your branding throughout the checkout experience and avoid opening different pages or windows. For website checkout flows in particular, opening new windows during the process can cause confusion and may even lead people to think they’ve been handed off to a different website." + }, + { + "type": "paragraph", + "text": "If Apple Pay is available, assume the person wants to use it. Consider presenting the Apple Pay button as the first payment option, displaying it larger than other options, or using a line to visually separate it from other choices." + }, + { + "type": "paragraph", + "text": "Accelerate single-item purchases with Apple Pay buttons on product detail pages. In addition to offering a shopping cart, consider putting Apple Pay buttons on product detail pages so people can purchase an individual item quickly. Purchases initiated in this way need to be for an individual item only, excluding any items that already reside in the shopping cart. If the shopping cart contains an item purchased directly from a product detail page, remove the item from the cart after the purchase is complete." + }, + { + "type": "paragraph", + "text": "Accelerate multi-item purchases with express checkout. Consider providing an express checkout feature that immediately displays the payment sheet, allowing people to purchase multiple items quickly using a single shipping method and destination. If you offer a coupon or promotional code, you can enhance the express checkout experience by letting people enter it on the payment sheet." + }, + { + "type": "paragraph", + "text": "Collect necessary information, like color and size options, before people reach the Apple Pay button. When additional information is needed at checkout time — perhaps because the customer forgot to choose an option — gracefully point out the problem and help them correct it. Use highlighting or warning text to identify missing information, and automatically navigate to the problematic field so people can correct it quickly and complete their purchase." + }, + { + "type": "paragraph", + "text": "Collect optional information before checkout begins. There’s no way to input optional data — like gift messages or delivery instructions — on the payment sheet, so collect this information ahead of time or even after the purchase is complete." + }, + { + "type": "paragraph", + "text": "Gather multiple shipping methods and destinations before showing the payment sheet. The payment sheet lets people select a single shipping method and destination for an entire order. If your customers can choose different shipping methods and destinations for individual items in an order, collect those details before Apple Pay checkout begins, instead of on the payment sheet." + }, + { + "type": "paragraph", + "text": "For in-store pickup, help people choose a pickup location before displaying the payment sheet. After a customer chooses the pickup location they want, use the read-only format to display the location’s address on the payment sheet. For developer guidance, see Displaying a Read-Only Pickup Address." + }, + { + "type": "paragraph", + "text": "Prefer information from Apple Pay. Assume that Apple Pay information is complete and up to date. Even if your app or website has existing contact, shipping, and payment information, consider fetching the latest from Apple Pay during checkout to reduce potential corrections." + }, + { + "type": "paragraph", + "text": "Avoid requiring account creation prior to purchase. If you want people to register for an account, ask them to do so on the order confirmation page. Prepopulate as many registration fields as possible using information provided by the payment sheet during checkout." + }, + { + "type": "paragraph", + "text": "Report the result of the transaction so that people can view it in the payment sheet. In failure cases, the payment sheet can display the errors that you provide, so people can take steps to fix the problem." + }, + { + "type": "paragraph", + "text": "Display an order confirmation or thank-you page. After the payment sheet shows the result of the transaction, display an order confirmation page to thank people for their purchase, provide details about when the order will ship, and indicate how to check its status. Listing Apple Pay on the confirmation page isn’t necessary, but if you do, show it after the last four digits of the account used to process the transaction or as a separate note. For example, ”1234 (Apple Pay)” or ”Paid with Apple Pay.”" + } + ] + }, + { + "heading": "Customizing the payment sheet", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Only present and request essential information. People may get confused or have privacy concerns if the payment sheet includes extraneous information. For example, it makes sense to see a contact email address but not a shipping address if the purchase is a gift card that will be delivered electronically. Showing or asking for a shipping address in this scenario may give the false impression that something will be physically delivered." + }, + { + "type": "paragraph", + "text": "Display the active coupon or promotional code, or give people a way to enter it. For example, if people can enter a code before the payment sheet appears, displaying it on the sheet can reassure them that the code works as they expect. Alternatively, allowing code entry on the payment sheet can be particularly beneficial in an express checkout flow." + }, + { + "type": "paragraph", + "text": "Let people choose the shipping method in the payment sheet. To the extent space permits, show a clear description, a cost, and, optionally, an estimated delivery or pickup date — or range of dates — for each available option. In iOS 15 and later, you can take advantage of the shipping method’s calendar and time-zone support to provide accurate delivery or pickup information, regardless of the customer’s current location. For developer guidance, see PKDateComponentsRange." + }, + { + "type": "paragraph", + "text": "For in-store pickup, consider letting people choose a pickup window that works for them. You can use the shipping method to supply a range of dates and times from which people can choose." + }, + { + "type": "paragraph", + "text": "Use line items to explain additional charges, discounts, pending costs, add-on donations, recurring, and future payments. A line item includes a label and cost; a line item for a recurring payment can also include a frequency. Don’t use line items to show an itemized list of products that make up the purchase. For developer guidance, see paymentSummaryItems; for guidance on donations, see Supporting donations." + }, + { + "type": "paragraph", + "text": "Keep line items short. Make line items specific and easily understandable at a glance. Whenever possible, fit line items on a single line." + }, + { + "type": "paragraph", + "text": "Provide a business name after the word Pay on the same line as the total. Use the same business name people will see when they look for the charge on their bank or credit card statement. This provides reassurance that payment is going to the right place. For example, Pay [Business_Name]." + }, + { + "type": "paragraph", + "text": "If you’re not the end merchant, specify both your business name and the end merchant’s name in the payment sheet. There are a few ways your app, App Clip, or website might help people make a purchase from an end merchant that’s unrelated to your company. For example, a marketplace app can help people make a purchase from an end merchant they might not recognize. Another example is an app that offers a self-checkout service people can use to pay for an item in an end merchant’s physical store without visiting the store’s checkout counter. In scenarios like these, people might not realize two businesses are involved in the transaction, so it’s essential to name both businesses and clarify their roles. When your app acts as an intermediary for an end merchant, clearly and succinctly describe the situation in the Pay line of the payment sheet, using something like Pay [End_Merchant_Business_Name (via Your_Business_Name)]." + }, + { + "type": "paragraph", + "text": "Clearly disclose when additional costs may be incurred after payment authorization. In some cases, the total cost may be unknown at checkout time. For example, the price of a car ride based on distance or time might change after checkout. Or, a customer might want to add a tip after a product is delivered. In situations like these, and when local regulations allow, you can provide a clear explanation in the payment sheet and a subtotal marked as Amount Pending. If you’re preauthorizing a specific amount, be sure the payment sheet accurately reflects this information." + }, + { + "type": "paragraph", + "text": "Handle data entry and payment errors gracefully. If an error occurs during checkout, help people resolve it quickly so they can complete their transaction. For related guidance, see Data validation." + } + ] + }, + { + "heading": "Displaying a website icon", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Many websites provide an icon that can display with bookmarks, in URL fields, or on a device’s Home screen. Websites that support Apple Pay can display this icon in a summary view and in the payment sheet of the connected device that’s used to authorize payment. The icon provides visual reassurance that payment is going to the right place." + }, + { + "type": "paragraph", + "text": "If your website supports Apple Pay, provide an icon in the following sizes for use in the summary view and the payment sheet:" + }, + { + "type": "table", + "rows": [ + [ + "@2x", + "@3x" + ], + [ + "60x60 pt (120x120 px @2x)", + "60x60 pt (180x180 px @3x)" + ] + ] + } + ] + }, + { + "heading": "Handling errors", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Provide clear, actionable guidance when problems occur during checkout or payment processing, so people can resolve problems quickly and complete their transaction." + } + ] + }, + { + "heading": "Data validation", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Your app or website can respond to user input when the payment sheet appears, when people change certain field values on the payment sheet, and after they authenticate the transaction. Use these opportunities to check for data entry problems and to provide clear and consistent messaging." + }, + { + "type": "paragraph", + "text": "Payment sheet error messaging" + }, + { + "type": "paragraph", + "text": "Custom detail view error messaging" + }, + { + "type": "paragraph", + "text": "Payment sheet error messaging" + }, + { + "type": "paragraph", + "text": "Custom detail view error messaging" + }, + { + "type": "paragraph", + "text": "When data is invalid, system-provided error messaging calls attention to relevant fields on the payment sheet. People can choose a field to view additional details and resolve the problem. Provide customized error messages for the detail view that appears when people choose a problematic field." + }, + { + "type": "paragraph", + "text": "For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and Apple Pay on the Web (web)." + }, + { + "type": "note", + "text": "NoteFor privacy reasons, your app or website has limited access to data until people attempt to authorize a transaction. Prior to authorization, only the card type and a redacted shipping address are accessible. It’s critical to display errors when authorization fails, but to the extent possible, you also need to attempt to validate available information and report problems before authorization." + }, + { + "type": "paragraph", + "text": "Avoid forcing compliance with your business logic. Design a data validation process that’s intelligent enough to ignore irrelevant data and infer missing data whenever possible. For example, if your app requires a five-digit zip code but someone enters a Zip+4 code, ignore the additional digits rather than asking for a correction. Let people enter phone numbers in multiple formats — such as with and without dashes, and with and without a country code — without producing an error." + }, + { + "type": "paragraph", + "text": "Provide accurate status reporting to the system. When a problem occurs, it’s essential that your app or website accurately indicate the type of problem so the system can show the most relevant error message on the payment sheet. This is done by accompanying your custom error message with the correct status code. For developer guidance, see PKPaymentError (iOS, watchOS) and Apple Pay Status Codes (web)." + }, + { + "type": "paragraph", + "text": "Succinctly and specifically describe the problem when data is invalid or incorrectly formatted. Reference the relevant field and indicate exactly what’s expected. For example, if people enter an invalid zip code, instead of showing “Address is invalid,” show a specific message like “Zip code doesn’t match city.” If the shipping address is unserviceable, indicate why with a message like “Shipping not available for this state.” Use noun phrases with sentence-style capitalization and no ending punctuation. Aim to keep messages at 128 characters or fewer to avoid truncation." + } + ] + }, + { + "heading": "Payment processing", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Handle interruptions correctly. A user-driven event like a cancellation or a system-driven event like a timeout could cause an interruption in the payment flow, resulting in the payment sheet being dismissed. When such an event occurs, you must cancel any in-progress payment. After the payment sheet dismisses, people can restart the process by choosing the Apple Pay button again. For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and oncancel (web)." + } + ] + }, + { + "heading": "Supporting subscriptions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Your app or website can use Apple Pay to request authorization for recurring fees. A recurring fee can be a fixed amount, such as a monthly movie ticket subscription, or — when local regulations allow — a variable amount like a weekly grocery order. The initial authorization can also include discounts and additional fees." + }, + { + "type": "paragraph", + "text": "Fixed subscription" + }, + { + "type": "paragraph", + "text": "Variable subscription (where local regulations allow)" + }, + { + "type": "paragraph", + "text": "Fixed subscription" + }, + { + "type": "paragraph", + "text": "Variable subscription (where local regulations allow)" + }, + { + "type": "paragraph", + "text": "Clarify subscription details before showing the payment sheet. Before asking people to authorize a recurring payment, make sure they fully understand the billing frequency and any other terms of service. You can reiterate the billing frequency on the payment sheet." + }, + { + "type": "paragraph", + "text": "Include line items that reiterate billing frequency, discounts, and additional upfront fees. Use these line items to remind people what they’re authorizing. If no payment is required at authorization time, clearly disclose when billing will occur." + }, + { + "type": "paragraph", + "text": "No payment required at authorization" + }, + { + "type": "paragraph", + "text": "No payment required at authorization" + }, + { + "type": "paragraph", + "text": "Clarify the current payment amount in the total line. Make sure people know the amount they’re being billed at the time of authorization." + }, + { + "type": "paragraph", + "text": "Only show the payment sheet when a subscription change results in additional fees. When the someone changes a subscription, authorization isn’t necessary if the cost decreases or remains the same." + } + ] + }, + { + "heading": "Supporting donations", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Approved nonprofits can use Apple Pay to accept donations." + }, + { + "type": "paragraph", + "text": "Use a line item to denote a donation. Display a line item on the payment sheet that reminds people they’re authorizing a donation; for example, display Donation $50.00." + }, + { + "type": "paragraph", + "text": "Streamline checkout by offering predefined donation amounts. You can reduce steps in the donation process by offering one-step recommended donations, like $25, $50, $100. Be sure to include an Other Amount option too, so people can customize the donation if they prefer." + } + ] + }, + { + "heading": "Using Apple Pay buttons", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The system provides several Apple Pay button types and styles you can use in your app or website. In contrast to the Apple Pay buttons, you use the Apple Pay mark to communicate the availability of Apple Pay as a payment option." + }, + { + "type": "paragraph", + "text": "Don’t create your own Apple Pay button design or attempt to mimic the system-provided button designs." + }, + { + "type": "paragraph", + "text": "For developer guidance, see PKPaymentButtonType and PKPaymentButtonStyle (iOS and macOS), WKInterfacePaymentButton (watchOS), and Apple Pay on the Web (web)." + } + ] + }, + { + "heading": "Button types", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Apple provides several types of buttons so you can choose the button type that fits best with the terminology and flow of your purchase or payment experience." + }, + { + "type": "paragraph", + "text": "Use the Apple-provided APIs to create Apple Pay buttons. When you use the system-provided APIs, you get:" + }, + { + "type": "list", + "items": [ + "A button that is guaranteed to use an Apple-approved caption, font, color, and style", + "Assurance that the button’s contents maintain ideal proportions as you change its size", + "Automatic translation of the button’s caption into the language that’s set for the device", + "Support for configuring the button’s corner radius to match the style of your UI", + "A system-provided alternative text label that lets VoiceOver describe the button" + ] + }, + { + "type": "table", + "rows": [ + [ + "Payment button type", + "Example usage" + ], + [ + "", + "An area in an app or website where people can make a purchase, such as a product detail page or shopping cart page." + ], + [ + "", + "An app or website that lets people pay bills or invoices, such as those for a utility — like cable or electricity — or a service like plumbing or car repair." + ], + [ + "", + "An app or website offering a shopping cart or purchase experience that includes other payment buttons that start with the text Check out." + ], + [ + "", + "An app or website offering a shopping cart or purchase experience that includes other payment buttons that start with the text Continue with." + ], + [ + "", + "An app or website that helps people book flights, trips, or other experiences." + ], + [ + "", + "An app or website for an approved nonprofit that lets people make donations." + ], + [ + "", + "An app or website that lets people purchase a subscription, such as a gym membership or a meal-kit delivery service." + ], + [ + "", + "An app or website that uses the term reload to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." + ], + [ + "", + "An app or website that uses the term add money to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." + ], + [ + "", + "An app or website that uses the term top up to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." + ], + [ + "", + "An app or website that lets people place orders for items like meals or flowers." + ], + [ + "", + "An app or website that lets people rent items like cars or scooters." + ], + [ + "", + "An app or website that uses the term support to help people give money to projects, causes, organizations, and other entities." + ], + [ + "", + "An app or website that uses the term contribute to help people give money to projects, causes, organizations, and other entities." + ], + [ + "", + "An app or website that lets people tip for goods or services." + ], + [ + "", + "An app or website that has stylistic reasons to use a button that can have a smaller minimum width or that doesn’t specify a call to action. If you choose a payment button type that isn’t supported on the version of the operating system your app or website is running in, the system may replace it with this button." + ] + ] + }, + { + "type": "paragraph", + "text": "When a device supports Apple Pay, but it hasn’t been set up yet, you can use the Set up Apple Pay button to show that Apple Pay is accepted and to give people an explicit opportunity to set it up." + }, + { + "type": "paragraph", + "text": "You can display the Set up Apple Pay button on pages such as a Settings page, a user profile screen, or an interstitial page. Tapping the button in any of these locations needs to initiate the process of adding a card." + } + ] + }, + { + "heading": "Button styles", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "You can use the automatic style to let the current system appearance determine the appearance of the Apple Pay buttons in your app (for developer guidance, see PKPaymentButtonStyle.automatic). If you want to control the button appearance yourself, you can use one of the following options. For web developer guidance, see ApplePayButtonStyle." + } + ] + }, + { + "heading": "Black", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use on white or light-color backgrounds that provide sufficient contrast. Don’t use on black or dark backgrounds." + } + ] + }, + { + "heading": "White with outline", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use on white or light-color backgrounds that don’t provide sufficient contrast. Don’t place on dark or saturated backgrounds." + } + ] + }, + { + "heading": "White", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use on dark-color backgrounds that provide sufficient contrast." + } + ] + }, + { + "heading": "Button size and position", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Prominently display the Apple Pay button. Make the Apple Pay button no smaller than other payment buttons, and avoid making people scroll to see it." + }, + { + "type": "paragraph", + "text": "Position the Apple Pay button correctly in relation to an Add to Cart button. In a side-by-side layout, place the Apple Pay button to the right of an Add to Cart button." + }, + { + "type": "paragraph", + "text": "In a stacked layout, place the Apple Pay button above an Add to Cart button." + }, + { + "type": "paragraph", + "text": "Adjust the corner radius to match the appearance of other buttons. By default, an Apple Pay button has rounded corners. You can change the corner radius to produce a button with square corners or a capsule-shape button. For developer guidance, see cornerRadius." + }, + { + "type": "paragraph", + "text": "Minimum corner radius" + }, + { + "type": "paragraph", + "text": "Default corner radius" + }, + { + "type": "paragraph", + "text": "Maximum corner radius" + }, + { + "type": "paragraph", + "text": "Maintain the minimum button size and margins around the button. Be mindful that the button title may vary in length depending on the locale." + }, + { + "type": "note", + "text": "NoteIf the size you specify doesn’t accommodate the translated title for the type of payment button you’re using, the system automatically replaces it with the plain Apple Pay button shown below on the left. There is no automatic replacement for the Set up Apple Pay button." + }, + { + "type": "paragraph", + "text": "Use the following values for guidance." + }, + { + "type": "table", + "rows": [ + [ + "Button", + "Minimum width", + "Minimum height", + "Minimum margins" + ], + [ + "Apple Pay", + "100pt (100px @1x, 200px @2x)", + "30pt (30px @1x, 60px @2x)", + "1/10 of the button’s height" + ], + [ + "Book with Apple Pay", + "140pt (140px @1x, 280px @2x)", + "30pt (30px @1x, 60px @2x)", + "1/10 of the button’s height" + ], + [ + "Buy with Apple Pay" + ], + [ + "Check out with Apple Pay" + ], + [ + "Donate with Apple Pay" + ], + [ + "Set up Apple Pay" + ], + [ + "Subscribe with Apple Pay" + ] + ] + } + ] + }, + { + "heading": "Apple Pay mark", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use the Apple Pay mark graphic to show that Apple Pay is an available payment option when showing other payment options in a similar manner. The Apple Pay mark isn’t a button; if you need an Apple Pay button, choose one of the buttons described in Button types. For design guidance related to showing Apple Pay as a payment option, see Offering Apple Pay." + }, + { + "type": "paragraph", + "text": "Use only the artwork provided by Apple, with no alterations other than height. You can specify a height for the Apple Pay mark, but make sure that the height you use is equal to or larger than other payment brand marks in your payment flow. Don’t adjust the width, corner radius, or aspect ratio of the artwork; don’t add a trademark symbol or any other content; don’t remove the border; don’t add visual effects to the mark, such as shadows, glows, or reflections; and don’t flip, rotate, or animate the Apple Pay mark." + }, + { + "type": "paragraph", + "text": "Maintain a minimum clear space around the mark of 1/10 of its height. Don’t let the Apple Pay mark share its surrounding border with another graphic or button." + }, + { + "type": "paragraph", + "text": "Download the Apple Pay mark graphic and full usage guidelines here." + } + ] + }, + { + "heading": "Referring to Apple Pay", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "As with all Apple product names, use Apple Pay exactly as shown in Apple Trademark List — never make it plural or possessive — and adhere to Guidelines for Using Apple Trademarks." + }, + { + "type": "paragraph", + "text": "You can use plain text to promote Apple Pay and indicate that Apple Pay is a payment option." + }, + { + "type": "paragraph", + "text": "Capitalize Apple Pay in text as it appears in the Apple Trademark list. Use two words with an uppercase A, an uppercase P, and lowercase for all other letters. Display Apple Pay entirely in uppercase only when doing so is necessary for conforming to an established, typographic interface style, such as in an app that capitalizes all text." + }, + { + "type": "paragraph", + "text": "Never use the Apple logo to represent the name Apple in text. In the United States, use the registered trademark symbol (®) the first time Apple Pay appears in body text. Don’t include a registered trademark symbol when Apple Pay appears as a selection option during checkout." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Purchase with Apple Pay" + ], + [ + "", + "Purchase with Apple Pay®" + ], + [ + "", + "Purchase with ApplePay" + ], + [ + "", + "Purchase with  Pay" + ], + [ + "", + "Purchase with APPLE PAY" + ] + ] + }, + { + "type": "paragraph", + "text": "Coordinate the font face and size with your app. Don’t mimic Apple typography. Instead, use text attributes that are consistent with the rest of your app or website." + }, + { + "type": "paragraph", + "text": "Don’t translate Apple Pay or any other Apple trademark. Always use Apple trademarks in English, even when they appear within non-English text." + }, + { + "type": "paragraph", + "text": "In a payment selection context, you can display a text-only description of Apple Pay only when all payment options have text-only descriptions. If any other payment option description includes an icon or logo, you must use the Apple Pay mark as described in Offering Apple Pay." + }, + { + "type": "paragraph", + "text": "When promoting your app’s use of Apple Pay, follow App Store guidelines. Before promoting Apple Pay for your app, refer to the App Store marketing guidelines." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, visionOS, or watchOS. Not supported in tvOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Pay Marketing Guidelines" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Pay — PassKit" + }, + { + "type": "paragraph", + "text": "Apple Pay on the Web" + }, + { + "type": "paragraph", + "text": "WKInterfacePaymentButton — WatchKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 16, 2025", + "Clarified supported platforms, including web browsers and Apple Vision Pro." + ], + [ + "June 10, 2024", + "Updated links to developer guidance for offering Apple Pay on the web." + ], + [ + "September 12, 2023", + "Updated artwork." + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "In-app purchase", + "url": "/design/human-interface-guidelines/in-app-purchase" + }, + { + "title": "Offering Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay#Offering-Apple-Pay" + }, + { + "title": "Streamlining checkout", + "url": "/design/human-interface-guidelines/apple-pay#Streamlining-checkout" + }, + { + "title": "Customizing the payment sheet", + "url": "/design/human-interface-guidelines/apple-pay#Customizing-the-payment-sheet" + }, + { + "title": "Supporting donations", + "url": "/design/human-interface-guidelines/apple-pay#Supporting-donations" + }, + { + "title": "Data validation", + "url": "/design/human-interface-guidelines/apple-pay#Data-validation" + }, + { + "title": "Displaying a website icon", + "url": "/design/human-interface-guidelines/apple-pay#Displaying-a-website-icon" + }, + { + "title": "Handling errors", + "url": "/design/human-interface-guidelines/apple-pay#Handling-errors" + }, + { + "title": "Payment processing", + "url": "/design/human-interface-guidelines/apple-pay#Payment-processing" + }, + { + "title": "Supporting subscriptions", + "url": "/design/human-interface-guidelines/apple-pay#Supporting-subscriptions" + }, + { + "title": "Using Apple Pay buttons", + "url": "/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons" + }, + { + "title": "Apple Pay mark", + "url": "/design/human-interface-guidelines/apple-pay#Apple-Pay-mark" + }, + { + "title": "Button types", + "url": "/design/human-interface-guidelines/apple-pay#Button-types" + }, + { + "title": "Button styles", + "url": "/design/human-interface-guidelines/apple-pay#Button-styles" + }, + { + "title": "Black", + "url": "/design/human-interface-guidelines/apple-pay#Black" + }, + { + "title": "White with outline", + "url": "/design/human-interface-guidelines/apple-pay#White-with-outline" + }, + { + "title": "White", + "url": "/design/human-interface-guidelines/apple-pay#White" + }, + { + "title": "Button size and position", + "url": "/design/human-interface-guidelines/apple-pay#Button-size-and-position" + }, + { + "title": "Referring to Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay#Referring-to-Apple-Pay" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/apple-pay#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/apple-pay#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/apple-pay#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/apple-pay#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/apple-pay#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/apple-pay#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Augmented reality", + "url": "https://developer.apple.com/design/human-interface-guidelines/augmented-reality", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Using the device’s camera to present the physical world onscreen live, your app can superimpose three-dimensional virtual objects, creating the illusion that these objects actually exist. Depending on the platform and the experiences your app offers, people can reorient the device to explore the objects from different angles, interact with objects using gestures and movement, and even join other people in multiuser AR experiences. For developer guidance, see ARKit." + }, + { + "type": "paragraph", + "text": "Offer AR features only on capable devices. If your app’s primary purpose is AR, make your app available only to devices that support ARKit. If your app includes features that require specific AR capabilities, or if AR features are optional in your app, don’t show people an error if they try to use these features on a device that doesn’t support them; instead, simply avoid offering the feature on an unsupported device. For developer guidance, see Verifying Device Support and User Permission." + }, + { + "type": "note", + "text": "NoteThe following guidance applies to apps that run in iOS and iPadOS. To learn about using ARKit to create immersive augmented reality experiences in visionOS, see ARKit." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people use the entire display. Devote as much of the screen as possible to displaying the physical world and your app’s virtual objects. Avoid cluttering the screen with controls and information that diminish the immersive experience." + }, + { + "type": "paragraph", + "text": "Strive for convincing illusions when placing realistic objects. Design detailed 3D assets with lifelike textures to create objects that appear to inhabit the physical environment in which you place them. Using information from ARKit, you can scale objects properly and position them on detected real-world surfaces, reflect environmental lighting conditions and simulate camera grain, cast top-down diffuse object shadows on real-world surfaces, and update visuals as the camera’s position changes. To help avoid breaking the illusion you create, make sure your app updates scenes 60 times per second so objects don’t appear to jump or flicker." + }, + { + "type": "paragraph", + "text": "Consider how virtual objects with reflective surfaces show the environment. Reflections in ARKit are approximations based on the environment captured by the camera. To help maintain the illusion that an AR experience is real, prefer small or coarse reflective surfaces that downplay the effect of these approximations." + }, + { + "type": "paragraph", + "text": "Use audio and haptics to enhance the immersive experience. A sound effect or bump sensation is a great way to confirm that a virtual object has made contact with a physical surface or other virtual object. Background music can also help envelop people in the virtual world. For guidance, see Playing audio and Playing haptics." + }, + { + "type": "paragraph", + "text": "Minimize text in the environment. Display only the information that people need for your app experience." + }, + { + "type": "paragraph", + "text": "If additional information or controls are necessary, consider displaying them in screen space. Content in screen space appears fixed to a consistent location either in the virtual world or, less commonly, on the device screen. It’s typically easy for people to find and view content in screen space because it remains stationary while the underlying AR environment moves with the device." + }, + { + "type": "paragraph", + "text": "Consider using indirect controls when you need to provide persistent controls. Indirect controls are not part of the virtual environment — instead, they are 2D controls displayed in screen space. If people need access to persistent controls in your app, consider placing the controls so that people don’t have to adjust how they’re holding the device to reach them. Also, consider using translucency in an indirect control to help avoid blocking the underlying scene. For example, the Measure app uses screen space to display a mix of translucent and opaque controls that people use to measure objects in the real world." + }, + { + "type": "paragraph", + "text": "Anticipate that people will use your app in a wide variety of real-world environments. People may open your app in a place where there isn’t much room to move around or there aren’t any large, flat surfaces. Clearly communicate your app’s requirements and expectations to people up front to help them understand how their physical environment can affect their AR experience. You might also consider offering different sets of features for use in different environments." + }, + { + "type": "paragraph", + "text": "Be mindful of people’s comfort. Holding a device at a certain distance or angle for a prolonged period can be fatiguing. To help avoid causing fatigue, consider placing objects at a distance that reduces the need to move the device closer to the object; in a game, consider keeping levels short and intermixed with brief periods of downtime." + }, + { + "type": "paragraph", + "text": "If your app encourages people to move, introduce motion gradually. For example, you might not want to make people dodge a virtual projectile as soon as they enter your AR game. Give people time to adapt to the AR experience in your app and then progressively encourage movement." + }, + { + "type": "paragraph", + "text": "Be mindful of people’s safety. When people are immersed in an AR experience, they’re not necessarily aware of their physical surroundings, so making rapid, sweeping, or expansive motions might be dangerous. Consider ways of making your app safe to operate; for example, a game could avoid encouraging large or sudden movements." + } + ] + }, + { + "heading": "Providing coaching", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Before people can enjoy an AR experience in your app, they need to move their device in ways that lets ARKit evaluate the surroundings and detect surfaces. Consider using the built-in coaching view to show people what to do and provide feedback during the initialization process. You can also use the coaching view to help people reinitialize AR — a process known as relocalization — after an AR experience is interrupted by, for example, people switching briefly to a different app. For guidance on relocalization, see Handling interruptions; for developer guidance, see ARCoachingOverlayView." + }, + { + "type": "paragraph", + "text": "Hide unnecessary app UI while people are using a coaching view. By default, the coaching view appears automatically when initialization or relocalization starts, so be prepared to hide unrelated UI to help people concentrate on the coaching view’s instructions." + }, + { + "type": "paragraph", + "text": "If necessary, offer a custom coaching experience. Although you can configure the system-provided coaching view to help people provide specific information — such as the detection of a horizontal or vertical plane — you might need additional information or want to use a different visual style. If you want to design a custom coaching experience, use the system-provided coaching view for reference." + } + ] + }, + { + "heading": "Helping people place objects", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Show people when to locate a surface and place an object. You can use the system-provided coaching view to help people find a horizontal or vertical flat surface on which to place an object. After ARKit detects a surface, your app can display a custom visual indicator to show when object placement is possible. You can help people understand how the placed object will look in the environment by aligning your indicator with the plane of the detected surface." + }, + { + "type": "paragraph", + "text": "App-specific indicator" + }, + { + "type": "paragraph", + "text": "When people place an object, immediately integrate that object into the AR environment. Although surface detection quickly and progressively refines accuracy, it’s best to avoid waiting for more accurate data before placing an object. Use the information available to respond instantly when people place an object; then, when surface detection completes, subtly refine the object’s position if necessary. For example, if people place an object beyond the bounds of the detected surface, gently nudge the object back onto the surface. For developer guidance on refining an object’s position, see ARTrackedRaycast." + }, + { + "type": "paragraph", + "text": "Consider guiding people toward offscreen virtual objects. Sometimes, it can be difficult for people to locate an object that’s positioned offscreen. When this is the case, you can help people find such objects by offering visual or audible cues. For example, if an object is offscreen to the left, you could display an indicator along the left edge of the screen that guides people to point the camera in that direction." + }, + { + "type": "paragraph", + "text": "Avoid trying to precisely align objects with the edges of detected surfaces. In AR, surface boundaries are approximations that may change as people’s surroundings are further analyzed." + }, + { + "type": "paragraph", + "text": "Incorporate plane classification information to inform object placement. For example, only let people place a virtual piece of furniture on a plane that’s classified as “floor,” or require a plane to be classified as “table” in order to place a virtual game board." + } + ] + }, + { + "heading": "Designing object interactions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people use direct manipulation to interact with objects when possible. It’s more immersive and intuitive when people can interact with onscreen 3D objects by touching them directly, than by using indirect controls in screen space. However, in situations where people are moving around as they use your app, indirect controls can work better." + }, + { + "type": "paragraph", + "text": "Direct manipulation" + }, + { + "type": "paragraph", + "text": "Indirect controls" + }, + { + "type": "paragraph", + "text": "Let people directly interact with virtual objects using standard, familiar gestures. For example, consider supporting a single-finger drag gesture for moving objects, and a two-finger rotation gesture for spinning objects. For guidance, see Gestures." + }, + { + "type": "paragraph", + "text": "In general, keep interactions simple. Touch gestures are inherently two-dimensional, but an AR experience involves the three dimensions of the real world. Consider the following approaches to simplifying people’s interactions with virtual objects." + }, + { + "type": "paragraph", + "text": "Limit movement to the two-dimensional surface on which the object rests." + }, + { + "type": "paragraph", + "text": "Limit object rotation to a single axis." + }, + { + "type": "paragraph", + "text": "Respond to gestures within reasonable proximity of interactive virtual objects. It can be difficult for people to be precise when aiming to touch specific points on objects that are small, thin, or placed at a distance. When your app detects a gesture near an interactive object, it’s usually best to assume that people want to affect that object." + }, + { + "type": "paragraph", + "text": "Let people initiate object scaling when it makes sense in your app. For example, if your app lets people explore an imaginary environment, it probably makes sense to support object scaling because your app doesn’t need to represent the real world. On the other hand, if your app helps shoppers decide on furniture to buy, letting people scale a chair object doesn’t help them visualize how the chair will look in a room." + }, + { + "type": "tip", + "text": "TipRegardless of the purpose of your app, don’t use scaling as a way to adjust the distance of an object. If you enlarge a distant object in an effort to make it appear closer, the result is a larger object that still looks far away." + }, + { + "type": "paragraph", + "text": "Be wary of potentially conflicting gestures. A two-finger pinch gesture, for example, is similar to a two-finger rotation gesture. If you implement two similar gestures like this, be sure to test your app and make sure they’re interpreted properly." + }, + { + "type": "paragraph", + "text": "Strive for virtual object movement that’s consistent with the physics of your app’s AR environment. People don’t necessarily expect an object to move smoothly over a rough or uneven surface, but they do expect objects to remain visible during movement. Aim to keep moving objects attached to real-world surfaces and avoid causing objects to jump or vanish and reappear as people resize, rotate, or move them." + }, + { + "type": "paragraph", + "text": "Explore even more engaging methods of interaction. Gestures aren’t the only way for people to interact with virtual objects in AR. Your app can use other factors, like motion and proximity, to bring content to life. A game character, for example, could turn its head to look at a person as they walk toward it." + } + ] + }, + { + "heading": "Offering a multiuser experience", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When multiple people share your app’s AR experience, each participant maps the environment independently and ARKit automatically merges the maps. For developer guidance, see isCollaborationEnabled." + }, + { + "type": "paragraph", + "text": "Consider allowing people occlusion. If your app supports placing virtual objects behind people who appear in the device’s camera feed, enhance the illusion of reality by letting the people occlude the objects. For developer guidance, see Occluding virtual content with people." + }, + { + "type": "paragraph", + "text": "When possible, let new participants enter a multiuser AR experience. Unless your app requires all participants to join before the experience begins, consider using implicit map merging to let new people quickly join an ongoing AR experience. For developer guidance, see isCollaborationEnabled." + } + ] + }, + { + "heading": "Reacting to real-world objects", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can enhance an AR experience by using known images and objects in the real-world environment to make virtual content appear. For example, an app that recognizes theater posters for a sci-fi film could cause virtual space ships to emerge from the posters and fly around the environment. Another example is an app for an art museum that presents a virtual tour guide when it recognizes a sculpture. To support experiences like these, your app provides a set of 2D reference images or 3D reference objects, and ARKit indicates when and where it detects any of these items in the current environment. For developer guidance, see Detecting Images in an AR Experience." + }, + { + "type": "paragraph", + "text": "When a detected image first disappears, consider delaying the removal of virtual objects that are attached to it. ARKit doesn’t track changes to the position or orientation of each detected image. To help prevent virtual objects from flickering, consider waiting up to one second before fading them out or removing them." + }, + { + "type": "paragraph", + "text": "Limit the number of reference images in use at one time. Image detection performance works best when ARKit looks for 100 or fewer distinct images in the real-world environment. If you need more than 100 reference images, you can change the set of active reference images based on context. For example, a museum guide app could ask permission to use location services to determine the part of the museum a person is in, and then look only for images displayed in that area." + }, + { + "type": "paragraph", + "text": "Limit the number of reference images requiring an accurate position. Updating the position of a reference image requires more resources. Use a tracked image when the image may move in the environment or when an attached animation or virtual object is small compared to the size of the image." + } + ] + }, + { + "heading": "Communicating with people", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If you must display instructional text, use approachable terminology. AR is an advanced concept that may be intimidating to some people. To help make it approachable, avoid using technical terms like ARKit, world detection, and tracking. Instead, use friendly, conversational terms that most people will understand." + }, + { + "type": "table", + "rows": [ + [ + "Do", + "Don’t" + ], + [ + "Unable to find a surface. Try moving to the side or repositioning your phone.", + "Unable to find a plane. Adjust tracking." + ], + [ + "Tap a location to place the [name of object to be placed].", + "Tap a plane to anchor an object." + ], + [ + "Try turning on more lights and moving around.", + "Insufficient features." + ], + [ + "Try moving your phone more slowly.", + "Excessive motion detected." + ] + ] + }, + { + "type": "paragraph", + "text": "In a three-dimensional context, prefer 3D hints. For example, placing a 3D rotation indicator around an object is more intuitive than displaying text-based instructions in a 2D overlay. Avoid displaying textual overlay hints in a 3D context unless people aren’t responding to contextual hints." + }, + { + "type": "paragraph", + "text": "Prefer a 3D hint in a 3D context." + }, + { + "type": "paragraph", + "text": "If necessary, use a 2D hint in a 3D context." + }, + { + "type": "paragraph", + "text": "Make important text readable. Use screen space to display text used for critical labels, annotations, and instructions. If you need to display text in 3D space, make sure the text faces people and that you use the same type size regardless of the distance between the text and the labeled object." + }, + { + "type": "paragraph", + "text": "If necessary, provide a way to get more information. Design a visual indicator that fits with your app experience to show people that they can tap for more information." + }, + { + "type": "paragraph", + "text": "Camera view" + }, + { + "type": "paragraph", + "text": "Detail view" + } + ] + }, + { + "heading": "Handling interruptions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "ARKit can’t track device position and orientation during an interruption, such as when people briefly switch to another app or accept a phone call. After an interruption ends, previously placed virtual objects are likely to appear in the wrong real-world positions. When you support relocalization, ARKit attempts to restore those virtual objects to their original real-world positions using new information. For developer guidance, see Managing Session Life Cycle and Tracking Quality." + }, + { + "type": "paragraph", + "text": "Consider using the system-provided coaching view to help people relocalize. During relocalization, ARKit attempts to reconcile its previous state with new observations of the current environment. To make these observations more useful, you can use the coaching view to help people return the device to its previous position and orientation." + }, + { + "type": "paragraph", + "text": "Consider hiding previously placed virtual objects during relocalization. To avoid flickering or other unpleasant visual effects during relocalization, it can be best to hide virtual objects and redisplay them in their new positions." + }, + { + "type": "paragraph", + "text": "Minimize interruptions if your app supports both AR and non-AR experiences. One way to avoid interruptions is by embedding a non-AR experience within an AR experience so that people can handle the task without exiting and re-entering AR. For example, if your app helps people decide on a piece of furniture to purchase by placing the item in a room, you might let them change the upholstery without leaving the AR experience." + }, + { + "type": "paragraph", + "text": "Allow people to cancel relocalization. If people don’t position and orient their device near where it was before an interruption, relocalization continues indefinitely without success. If coaching people to resume their session isn’t successful, consider providing a reset button or other way to restart the AR experience." + }, + { + "type": "paragraph", + "text": "Indicate when the front-facing camera is unable to track a face for more than about half a second. Use a visual indicator to indicate that the camera can no longer track the person’s face. If you need to provide text instructions in this situation, keep them to a minimum." + } + ] + }, + { + "heading": "Suggesting problem resolutions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people reset the experience if it doesn’t meet their expectations. Don’t force people to wait for conditions to improve or struggle with object placement. Give them a way to start over again and see if they have better results." + }, + { + "type": "paragraph", + "text": "Sufficient lighting" + }, + { + "type": "paragraph", + "text": "Insufficient lighting" + }, + { + "type": "paragraph", + "text": "Suggest possible fixes if problems occur. Analysis of the real-world environment and surface detection can fail or take too long for a variety of reasons — insufficient light, an overly reflective surface, a surface without enough detail, or too much camera motion. If your app is notified of these problems, use straightforward, friendly language to offer suggestions for resolving them." + }, + { + "type": "table", + "rows": [ + [ + "Problem", + "Possible suggestion" + ], + [ + "Insufficient features detected.", + "Try turning on more lights and moving around." + ], + [ + "Excessive motion detected.", + "Try moving your phone slower." + ], + [ + "Surface detection takes too long.", + "Try moving around, turning on more lights, and making sure your phone is pointed at a sufficiently textured surface." + ] + ] + } + ] + }, + { + "heading": "Icons and badges", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apps can display an AR icon in controls that launch ARKit-based experiences. You can download this icon in Resources." + }, + { + "type": "paragraph", + "text": "Use the AR glyph as intended. The glyph is strictly for initiating an ARKit-based experience. Never alter the glyph (other than adjusting its size and color), use it for other purposes, or use it in conjunction with AR experiences not created using ARKit." + }, + { + "type": "paragraph", + "text": "Maintain minimum clear space. The minimum amount of clear space required around an AR glyph is 10% of the glyph’s height. Don’t let other elements infringe on this space or occlude the glyph in any way." + }, + { + "type": "paragraph", + "text": "Apps that include collections of products or other objects can use badging to identify specific items that can be viewed in AR using ARKit. For example, an app that sells vintage collectibles might use a badge to mark items that people can preview in their home before making a purchase." + }, + { + "type": "paragraph", + "text": "Use the AR badges as intended and don’t alter them. You can download AR badges, available in collapsed and expanded form, in Resources. Use these images exclusively to identify products or other objects that can be viewed in AR using ARKit. Never alter the badges, change their color, use them for other purposes, or use them in conjunction with AR experiences not created with ARKit." + }, + { + "type": "paragraph", + "text": "AR badge" + }, + { + "type": "paragraph", + "text": "Glyph-only AR badge" + }, + { + "type": "paragraph", + "text": "Prefer the AR badge to the glyph-only badge. In general, use the glyph-only badge for constrained spaces that can’t accommodate the AR badge. Both badges work well at their default size." + }, + { + "type": "paragraph", + "text": "Use badging only when your app contains a mixture of objects that can be viewed in AR and objects that cannot. If all objects in your app can be viewed in AR, then badging is redundant." + }, + { + "type": "paragraph", + "text": "Keep badge placement consistent and clear. A badge looks best when displayed in one corner of an object’s photo. Always place it in the same corner and make sure it’s large enough to be seen clearly (but not so large that it occludes important detail in the photo)." + }, + { + "type": "paragraph", + "text": "Maintain minimum clear space. The minimum amount of clear space required around an AR badge is 10% of the badge’s height. Don’t allow other elements to infringe on this space and occlude the badge in any way." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, or watchOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "With the wearer’s permission, you can use ARKit in your visionOS app to detect surfaces in a person’s surroundings, use a person’s hand and finger postions to inform your custom gestures, support interactions that incorporate nearby physical objects into your immersive experience, and more. For developer guidance, see ARKit." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Playing haptics" + }, + { + "type": "paragraph", + "text": "Gestures" + }, + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "ARKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/augmented-reality#Best-practices" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Playing haptics", + "url": "/design/human-interface-guidelines/playing-haptics" + }, + { + "title": "Providing coaching", + "url": "/design/human-interface-guidelines/augmented-reality#Providing-coaching" + }, + { + "title": "Handling interruptions", + "url": "/design/human-interface-guidelines/augmented-reality#Handling-interruptions" + }, + { + "title": "Helping people place objects", + "url": "/design/human-interface-guidelines/augmented-reality#Helping-people-place-objects" + }, + { + "title": "Designing object interactions", + "url": "/design/human-interface-guidelines/augmented-reality#Designing-object-interactions" + }, + { + "title": "Gestures", + "url": "/design/human-interface-guidelines/gestures" + }, + { + "title": "Offering a multiuser experience", + "url": "/design/human-interface-guidelines/augmented-reality#Offering-a-multiuser-experience" + }, + { + "title": "Reacting to real-world objects", + "url": "/design/human-interface-guidelines/augmented-reality#Reacting-to-real-world-objects" + }, + { + "title": "Communicating with people", + "url": "/design/human-interface-guidelines/augmented-reality#Communicating-with-people" + }, + { + "title": "Suggesting problem resolutions", + "url": "/design/human-interface-guidelines/augmented-reality#Suggesting-problem-resolutions" + }, + { + "title": "Icons and badges", + "url": "/design/human-interface-guidelines/augmented-reality#Icons-and-badges" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/augmented-reality#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/augmented-reality#visionOS" + }, + { + "title": "permission", + "url": "/design/human-interface-guidelines/privacy#visionOS" + }, + { + "title": "custom gestures", + "url": "/design/human-interface-guidelines/gestures#Designing-custom-gestures-in-visionOS" + }, + { + "title": "immersive experience", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/augmented-reality#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/augmented-reality#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/augmented-reality#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/augmented-reality#Videos" + } + ], + "image_count": 0 + }, + { + "title": "CarPlay", + "url": "https://developer.apple.com/design/human-interface-guidelines/carplay", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People download CarPlay apps from the App Store and install them on iPhone like any other app. When people connect their iPhone with their vehicle, app icons for installed CarPlay apps appear on the CarPlay Home screen." + }, + { + "type": "paragraph", + "text": "CarPlay is designed for drivers to use while they’re driving. Keep this context in mind as you design your CarPlay app, providing features that help people perform tasks quickly and with minimal interaction." + }, + { + "type": "paragraph", + "text": "To create the interface of your CarPlay app, you use the system-defined templates that are appropriate for the type of app you’re developing, such as audio, communication, navigation, or fueling. For each template, your app provides the content and iOS renders it in CarPlay. Because the system displays UI components and handles the interface with the vehicle, you don’t need to adjust your layout for different screen resolutions, or manage input from different types of hardware like touchscreens, knobs, or touch pads." + }, + { + "type": "paragraph", + "text": "To learn how to create various types of CarPlay apps and use the system-provided templates, see CarPlay App Programming Guide. The general design guidelines below apply to all types of CarPlay apps." + } + ] + }, + { + "heading": "iPhone interactions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "CarPlay shows compatible apps from the connected iPhone on the car’s built-in display, applying simplified interfaces that are optimized for use while driving." + }, + { + "type": "paragraph", + "text": "Eliminate app interactions on iPhone when CarPlay is active. Interactions with your app need to occur using the car’s built-in controls and display. If your app requires setup on iPhone, make sure people perform it before the vehicle is in motion." + }, + { + "type": "paragraph", + "text": "Never lock people out of CarPlay because the connected iPhone requires input. Your app needs to function when iPhone is inaccessible — for example, when people put it in a bag or in the trunk while driving. If people must resolve a problem on the connected iPhone, let them do so after the vehicle stops." + }, + { + "type": "paragraph", + "text": "Make sure your app works without requiring people to unlock iPhone. Most people use CarPlay while their iPhone is locked, so ensure that the features you provide in your CarPlay app work as expected in this scenario." + } + ] + }, + { + "heading": "Audio", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In CarPlay, keep in mind that your app coexists with other audio sources, such as the car’s own built-in radio and voice prompts from the navigation system. Regardless of whether audio is a primary aspect of your app’s experience, you need to know how people expect audio to behave so you can meet those expectations." + }, + { + "type": "paragraph", + "text": "Let people choose when to start playback. In general, avoid beginning playback automatically unless your app’s purpose is to play a single source of audio, or your app is resuming previously interrupted audio. Also, avoid starting an audio session until you’re ready to actually play audio because starting a session silences other audio sources, like the car’s built-in radio." + }, + { + "type": "paragraph", + "text": "Start playback as soon as audio has sufficiently loaded. After people make a selection, it may take several seconds for audio to begin playing, depending on buffering and network conditions. The system keeps the selection highlighted and displays a spinning activity indicator until your app signals that the audio is ready to play." + }, + { + "type": "paragraph", + "text": "Display the Now Playing screen when audio is ready to play. Don’t delay playback until descriptive information completes loading. If necessary, continue loading such information in the background, and show it when it’s available." + }, + { + "type": "paragraph", + "text": "Resume audio playback after an interruption only when it’s appropriate. For example, your app can resume audio after a temporary interruption like a phone call. Permanent interruptions, such as a music playlist initiated by Siri, are nonresumable. When a resumable interruption occurs, your app needs to resume playback when the interruption ends if audio was actively playing when the interruption started." + }, + { + "type": "paragraph", + "text": "When necessary, automatically adjust audio levels, but don’t change the overall volume. Although your app can adjust relative, independent volume levels to achieve a great mix of audio, people need to control the final output volume." + } + ] + }, + { + "heading": "Layout", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "CarPlay supports a wide range of display resolutions with varying pixel densities and aspect ratios. The system automatically scales app icons and interfaces based on the resolution of the display, so they always appear onscreen at roughly the same size. Some common screen sizes are listed in the table below." + }, + { + "type": "table", + "rows": [ + [ + "Dimensions (pixels)", + "Aspect ratio" + ], + [ + "800x480", + "5:3" + ], + [ + "960x540", + "16:9" + ], + [ + "1280x720", + "16:9" + ], + [ + "1920x720", + "8:3" + ] + ] + }, + { + "type": "paragraph", + "text": "Provide useful, high-value information in a clean layout that’s easy to scan from the driver’s seat. Don’t clutter the screen with nonessential details and unnecessary visual embellishments." + }, + { + "type": "paragraph", + "text": "Maintain an overall consistent appearance throughout your app. In general, ensure that elements with similar functions look similar." + }, + { + "type": "paragraph", + "text": "Ensure that primary content stands out and feels actionable. Large items tend to appear more important than smaller ones and are easier for people to tap. In general, place the most important content and controls in the upper half of the screen." + } + ] + }, + { + "heading": "Color", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Color can indicate interactivity, impart vitality, and provide visual continuity." + }, + { + "type": "paragraph", + "text": "In general, prefer a limited color palette that coordinates with your app logo. Subtle use of color is a great way to communicate your brand." + }, + { + "type": "paragraph", + "text": "Avoid using the same color for interactive and noninteractive elements. If interactive and noninteractive elements have the same color, it’s hard for people to know where to tap." + }, + { + "type": "paragraph", + "text": "Test your app’s color scheme under a variety of lighting conditions in an actual car. Lighting varies significantly based on time of day, weather, window tinting, and more. Colors you see on your computer at design time won’t always look the same when your app is used in the real world. Consider how color brightness might affect the experience of driving at night, and how low-contrast colors can wash out in direct sunlight. If necessary, make adjustments to provide the best possible viewing experience in the majority of use cases." + }, + { + "type": "paragraph", + "text": "Ensure your app looks great in both dark and light environments. CarPlay supports both light and dark appearances, and may automatically adjust the current appearance based on lighting conditions." + }, + { + "type": "paragraph", + "text": "Choose colors that help you communicate effectively with everyone. Different people see and interpret colors differently. For guidance on using colors in ways that people appreciate, see Inclusive color." + } + ] + }, + { + "heading": "Icons and images", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "CarPlay supports both landscape and portrait displays and both @2x (low resolution) and @3x (high resolution) scale factors." + }, + { + "type": "paragraph", + "text": "Supply high-resolution images with scale factors of @2x and @3x for all CarPlay artwork in your app. The system automatically shows the correct images and scales them appropriately, based on the resolution and size of the car’s display." + }, + { + "type": "paragraph", + "text": "Mirror your iPhone app icon. A well-designed app icon works well in CarPlay and on iPhone, without the need for a second design." + }, + { + "type": "paragraph", + "text": "Don’t use black for your icon’s background. Lighten a black background or add a border so the icon doesn’t blend into the display background." + }, + { + "type": "paragraph", + "text": "Create your CarPlay app icon in the following sizes:" + }, + { + "type": "table", + "rows": [ + [ + "@2x (pixels)", + "@3x (pixels)" + ], + [ + "120x120", + "180x180" + ] + ] + } + ] + }, + { + "heading": "Error handling", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A CarPlay app needs to handle errors gracefully and report them to people only when absolutely necessary." + }, + { + "type": "paragraph", + "text": "Report errors in CarPlay, not on the connected iPhone. If you must notify people of a problem, do so clearly in CarPlay. Never direct people to pick up their iPhone to read or resolve an error." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "CarPlay" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "CarPlay App Programming Guide" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "iPhone interactions", + "url": "/design/human-interface-guidelines/carplay#iPhone-interactions" + }, + { + "title": "Audio", + "url": "/design/human-interface-guidelines/carplay#Audio" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/carplay#Layout" + }, + { + "title": "Color", + "url": "/design/human-interface-guidelines/carplay#Color" + }, + { + "title": "Inclusive color", + "url": "https://developer.apple.com/design/human-interface-guidelines/color#Inclusive-color" + }, + { + "title": "Icons and images", + "url": "/design/human-interface-guidelines/carplay#Icons-and-images" + }, + { + "title": "Error handling", + "url": "/design/human-interface-guidelines/carplay#Error-handling" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/carplay#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/carplay#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/carplay#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/carplay#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/carplay#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/carplay#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "CareKit", + "url": "https://developer.apple.com/design/human-interface-guidelines/carekit", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "To learn more about CareKit, see Research & Care > CareKit." + }, + { + "type": "paragraph", + "text": "CareKit 2.0 contains two projects, CareKit UI and CareKit Store. CareKit UI provides a wide variety of prebuilt views you can use to create a custom CareKit app. CareKit Store defines a database scheme that incorporates CareKit entities — such as patients, care plans, tasks, and contacts — so you can store and manage data on the patient’s device. CareKit 2.0 provides seamless synchronization between your database and the UI, so you can always keep a care plan up to date. For developer guidance, see CareKit." + } + ] + }, + { + "heading": "Data and privacy", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Nothing is more important than protecting people’s privacy and safeguarding the extremely sensitive data your CareKit app collects and stores." + }, + { + "type": "paragraph", + "text": "Provide a coherent privacy policy. During the app submission process, you must provide a URL to a clearly stated privacy policy, so that people can view the policy when they click the link in the App Store page for your app. For developer guidance, see App information > App Store Connect help." + }, + { + "type": "paragraph", + "text": "In addition to the data that people enter into your CareKit app, you may be able to access data through iOS features and capabilities. You must receive people’s permission before accessing data through these features, and you must protect people’s data whether people enter it into your app or you get it from the device or the system. For developer guidance, see Protecting user privacy." + } + ] + }, + { + "heading": "HealthKit integration", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "HealthKit is the central repository for health and fitness data in iOS and watchOS. When you support HealthKit in your CareKit app, you can ask people for permission to access and share their health and fitness data with designated caregivers." + }, + { + "type": "paragraph", + "text": "Request access to health data only when you need it. It makes sense to request access to weight information when people log their weight, for example, but not immediately after your app launches. When your request is clearly related to the current context, you help people understand your app’s intentions. Also, people can change the permissions they grant, so it’s a good idea to make a request every time your app needs access. For developer guidance, see requestAuthorization(toShare:read:completion:)." + }, + { + "type": "paragraph", + "text": "Clarify your app’s intent by adding descriptive messages to the standard permission screen. People expect to see the system-provided permission screen when asked to approve access to health data. Write a few succinct sentences that explain why you need the information and how people can benefit from sharing it with your app. Avoid adding custom screens that replicate the standard permission screen’s behavior or content." + }, + { + "type": "paragraph", + "text": "Manage health data sharing solely through the system’s privacy settings. People expect to globally manage access to their health information in Settings > Privacy. Don’t confuse people by building additional screens in your app that affect the flow of health data." + }, + { + "type": "paragraph", + "text": "For related design guidance, see HealthKit. For developer guidance, see HealthKit." + } + ] + }, + { + "heading": "Motion data", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If it’s useful for treatment and if people give permission, your app can get motion information from the device to determine if people are standing still, walking, running, cycling, or driving. When people are walking or running, you can also determine the step count, pace, and number of flights of stairs ascended or descended." + }, + { + "type": "paragraph", + "text": "Motion information can also include custom data collected as part of physical therapy. For example, some ResearchKit tasks use device sensors to test flexibility, range of motion, and ambulatory capability." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Core Motion." + } + ] + }, + { + "heading": "Photos", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Pictures are a great way to communicate treatment progress. With people’s permission, your app can access the device’s camera and photos to share pictures with a care team. For example, a care plan might include a request for people to share periodic photos of an injury, so the physician can monitor the healing process." + }, + { + "type": "paragraph", + "text": "For developer guidance, see UIImagePickerController." + } + ] + }, + { + "heading": "ResearchKit integration", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A ResearchKit app lets people participate in important medical research studies. Your CareKit app can incorporate ResearchKit features to display related surveys, tasks, and charts, if appropriate. ResearchKit also includes an informed consent module, which your CareKit app can use to request people’s permission to collect and share data." + }, + { + "type": "paragraph", + "text": "For related design guidance, see ResearchKit. For developer guidance, see Research & Care > Developers." + } + ] + }, + { + "heading": "CareKit views", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "CareKit UI provides customizable views organized into three categories — tasks, charts, and contacts — and defines several default view styles in each. To design a CareKit app, you simply choose the view styles you need and supply CareKit Store data to display in them." + }, + { + "type": "paragraph", + "text": "Each view category is designed to support specific types of content and interaction. To ensure a consistent experience, use each view type for its intended purpose." + }, + { + "type": "table", + "rows": [ + [ + "Category", + "Purpose" + ], + [ + "Tasks", + "Present tasks, like taking medication or doing physical therapy. Support logging of patient symptoms and other data." + ], + [ + "Charts", + "Display graphical data that can help people understand how their treatment is progressing." + ], + [ + "Contact views", + "Display contact information. Support communication through phone, message, and email, and link to a map of the contact’s location." + ] + ] + }, + { + "type": "paragraph", + "text": "Tasks and charts" + }, + { + "type": "paragraph", + "text": "Contacts" + }, + { + "type": "paragraph", + "text": "A CareKit UI view consists of a header and may include a stack of content subviews. Located at the top of the view, the header can display text, a symbol, and a disclosure indicator, and can include a separator at its bottom edge. The content stack appears below the header and displays your content subviews in a vertical arrangement." + }, + { + "type": "paragraph", + "text": "CareKit UI takes care of all the layout constraints within a view, so you don’t have to worry about breaking existing constraints when you add new subviews to the stack." + } + ] + }, + { + "heading": "Tasks", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A care plan generally presents a set of prescribed actions for people to perform, such as taking medication, eating specific foods, exercising, or reporting symptoms. CareKit UI defines several styles of task views you can use to display prescribed actions. Typically, you customize a task view by providing the information to display, often by specifying data stored in an on-device CareKit Store database. In some cases, you might also supply custom UI elements." + }, + { + "type": "paragraph", + "text": "A task can contain the following types of information." + }, + { + "type": "table", + "rows": [ + [ + "Information", + "Required", + "Description", + "Example value" + ], + [ + "Title", + "Yes", + "A word or short phrase that introduces the task.", + "Ibuprofen" + ], + [ + "Schedule", + "Yes", + "The schedule on which a task must be completed.", + "Four times a day" + ], + [ + "Instructions", + "No", + "Detailed instructions, recommendations, and warnings.", + "Take 1 tablet every 4–6 hours (not to exceed 4 tablets daily)." + ], + [ + "Group ID", + "No", + "An identifier you can use to group similar tasks in ways that make sense in your app.", + "A category identifier like medication or exercise." + ] + ] + }, + { + "type": "paragraph", + "text": "In CareKit 2.0, CareKit UI defines five styles of task views: simple, instructions, log, checklist, and grid. Each style is designed to support a particular use case." + }, + { + "type": "paragraph", + "text": "Use the simple style for a one-step task. The default simple-style view consists of a header area that contains a title, subtitle, and button. You provide the title and subtitle, and you can provide a custom image to display in the button when the task is complete. If you don’t supply an image, CareKit shows that a task is complete by filling in the button and displaying a checkmark. Because the default simple-style view doesn’t include a content stack, consider using a different task style if you need to display additional content." + }, + { + "type": "paragraph", + "text": "Use the instructions style when you need to add informative text to a simple task. For example, if a single-step medication task needs to include additional information — such as “Take on an empty stomach” or “Take at bedtime” — you can use an instructions-style task to display it." + }, + { + "type": "paragraph", + "text": "Use the log style to help people log events. For example, you could use this task style to display a button people can tap whenever they feel nauseated. The log-style task can automatically display a timestamp every time the patient logs an event." + }, + { + "type": "paragraph", + "text": "Use the checklist style to display a list of actions or steps in a multistep task. For example, if people must take a medication three times per day, you could display the three scheduled times in a checklist. Each checklist item can include a text description and a button that people can tap to mark the item as done. By default, a checklist task can also display instructional text below the list." + }, + { + "type": "paragraph", + "text": "Use the grid style to display a grid of buttons in a multistep task. Like the checklist style, the grid style also supports a multistep task, but it displays the steps in a more compact arrangement. You can supply a succinct title for each button (if you need to provide additional description for each button, you might want to use the checklist style instead). By default, a grid-style task can also display instructional text below the grid of buttons. Unlike other task styles, the grid style gives you access to its underlying collection view, which means that you can display custom UI elements in the grid layout." + }, + { + "type": "paragraph", + "text": "Consider using color to reinforce the meaning of task items. Color can be a good way to help people understand information at a glance. For example, you could use one color for medications and a different color for physical activities. Always avoid using color as the only way to convey information. For guidance, see Color." + }, + { + "type": "paragraph", + "text": "Combine accuracy with simplicity when describing a task and its steps. For example, use a medication’s marketing name instead of its chemical description. Also, when the context of a task helps to clarify meaning, minimize the number of words you use. For example, a daily medication task generally tells people when to take specific medications, so it may be unnecessary to repeat words like take." + }, + { + "type": "paragraph", + "text": "Consider supplementing multistep or complex tasks with videos or images. Visually demonstrating how to perform a task can help people avoid mistakes." + } + ] + }, + { + "heading": "Charts", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Chart views let you present data and trends in graphical ways that can help people visualize their progress in a care plan. CareKit chart views can display both current and historical data, and update automatically with new data." + }, + { + "type": "paragraph", + "text": "In CareKit 2.0, CareKit UI provides three chart styles: bar, scatter, and line. For each style, you provide a descriptive title and subtitle, supply axis markers — like days of the week — and specify the data set." + }, + { + "type": "paragraph", + "text": "Bar chart" + }, + { + "type": "paragraph", + "text": "Scatter chart" + }, + { + "type": "paragraph", + "text": "Line chart" + }, + { + "type": "paragraph", + "text": "Consider highlighting narratives and trends to illustrate progress. For example, your app could display a bar chart that shows a correlation between the number of times people took medication and their level of pain. Displaying such data can encourage better adherence to a care plan." + }, + { + "type": "paragraph", + "text": "Label chart elements clearly and succinctly. Long, detailed labels can make a chart difficult to read and understand. Keep labels short and avoid repeating the same information. For example, a heart rate chart might use the term BPM in an axis label instead of using it in the label of every data point." + }, + { + "type": "paragraph", + "text": "Use distinct colors. In general, avoid using different shades of the same color to mean different things. Also ensure that you use colors with sufficient contrast. For related guidance, see Accessibility." + }, + { + "type": "paragraph", + "text": "Consider providing a legend to add clarity. If the colors you use to represent different types of data aren’t immediately clear, include a legend that clearly and succinctly describes them." + }, + { + "type": "paragraph", + "text": "Clearly denote units of time. People need to know whether time-based data is represented in seconds, minutes, hours, days, weeks, months, or years. If you don’t want to include this information in individual data value labels, include it in an axis label or elsewhere on the chart." + }, + { + "type": "paragraph", + "text": "Consolidate large data sets for greater readability. A large amount of data can make a chart unreadable by reducing the size of individual data points and presenting too much visible information. Look for ways to group and organize data for clarity and simplicity." + }, + { + "type": "paragraph", + "text": "If necessary, offset data to keep charts proportional. It’s easy for very small data points to get lost or become unreadable in a chart that also contains very large data points. If the difference between data points is significant, find ways to offset or restructure the data so all data points are readable." + }, + { + "type": "paragraph", + "text": "For developer guidance, see CareKit > Chart Interfaces. To learn about ResearchKit charts, see the ResearchKit GitHub project." + } + ] + }, + { + "heading": "Contact views", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A care plan typically includes a care team and other trusted individuals who can help patients follow the plan. CareKit UI defines a contact view you can use to help patients communicate with the people in their care plan." + }, + { + "type": "paragraph", + "text": "In CareKit 2.0, CareKit UI provides two styles of the contact view: simple and detailed." + }, + { + "type": "paragraph", + "text": "Simple" + }, + { + "type": "paragraph", + "text": "Detailed" + }, + { + "type": "paragraph", + "text": "Consider using color to categorize care team members. Color can help people identify care team members at a glance." + } + ] + }, + { + "heading": "Notifications", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Notifications can tell people when it’s time to take medication or complete a task, and badging your app icon can show that there’s an unread message from a caregiver. Apple Watch can also display a notification from your app; for guidance, see Notifications." + }, + { + "type": "paragraph", + "text": "Minimize notifications. Care plans vary from patient to patient. While one individual may have only a few daily tasks to complete, another may have a long list. Use notifications sparingly so people don’t feel overwhelmed. When possible, consider coalescing multiple items into a single notification." + }, + { + "type": "paragraph", + "text": "Consider providing a detail view. In addition to providing more information, a notification detail view can help people take immediate action without leaving their current context to open your app. For example, you could use a notification detail view to display a list of pending tasks so that people can quickly mark them as complete." + } + ] + }, + { + "heading": "Symbols and branding", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "CareKit uses a variety of built-in symbols to help people understand what they can do in a care app. For example, CareKit can display the phone, messaging, and envelope symbols in a contact view and the clock symbol in a log-style task view." + }, + { + "type": "paragraph", + "text": "Although you can customize the default symbols, most view styles work best with the CareKit-provided symbols. The exception is the highly customizable grid-style task view, which can display your custom UI in a grid layout." + }, + { + "type": "paragraph", + "text": "In a grid view, you might want to display custom symbols that are relevant to the unique content and experience in your app. You could use symbols to indicate the grouping of tasks; for example, a pill to represent medication tasks, or a person walking to represent exercise tasks. In this scenario, consider using SF Symbols to illustrate custom items in your app." + }, + { + "type": "paragraph", + "text": "Using SF Symbols in your app gives you:" + }, + { + "type": "list", + "items": [ + "Designs that coordinate with CareKit’s visual design language", + "Support for creating custom symbols to represent the unique content in your app" + ] + }, + { + "type": "paragraph", + "text": "Design a relevant care symbol. If you need to customize a symbol, be sure the design is closely related to your app or the general concept of health and wellness. Avoid creating a purely decorative symbol or using a corporate logo as a custom symbol." + }, + { + "type": "paragraph", + "text": "Incorporate refined, unobtrusive branding. People use CareKit apps to help them achieve their health and wellness goals; they don’t want to see advertising. To avoid distracting people from their care plan, subtly incorporate your brand through your app’s use of color and communication style." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Research & Care > CareKit" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "CareKit" + }, + { + "type": "paragraph", + "text": "Research & Care > Developers" + }, + { + "type": "paragraph", + "text": "Protecting user privacy — HealthKit" + }, + { + "type": "paragraph", + "text": "HealthKit" + }, + { + "type": "paragraph", + "text": "ResearchKit GitHub project" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Data and privacy", + "url": "/design/human-interface-guidelines/carekit#Data-and-privacy" + }, + { + "title": "HealthKit integration", + "url": "/design/human-interface-guidelines/carekit#HealthKit-integration" + }, + { + "title": "HealthKit", + "url": "/design/human-interface-guidelines/healthkit" + }, + { + "title": "Motion data", + "url": "/design/human-interface-guidelines/carekit#Motion-data" + }, + { + "title": "Photos", + "url": "/design/human-interface-guidelines/carekit#Photos" + }, + { + "title": "ResearchKit integration", + "url": "/design/human-interface-guidelines/carekit#ResearchKit-integration" + }, + { + "title": "ResearchKit", + "url": "/design/human-interface-guidelines/researchkit" + }, + { + "title": "CareKit views", + "url": "/design/human-interface-guidelines/carekit#CareKit-views" + }, + { + "title": "Tasks", + "url": "/design/human-interface-guidelines/carekit#Tasks" + }, + { + "title": "Charts", + "url": "/design/human-interface-guidelines/carekit#Charts" + }, + { + "title": "Contact views", + "url": "/design/human-interface-guidelines/carekit#Contact-views" + }, + { + "title": "Color", + "url": "/design/human-interface-guidelines/color" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Notifications", + "url": "/design/human-interface-guidelines/carekit#Notifications" + }, + { + "title": "Notifications", + "url": "/design/human-interface-guidelines/notifications" + }, + { + "title": "Symbols and branding", + "url": "/design/human-interface-guidelines/carekit#Symbols-and-branding" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/carekit#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/carekit#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/carekit#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/carekit#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/carekit#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/carekit#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Game Center", + "url": "https://developer.apple.com/design/human-interface-guidelines/game-center", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Supporting Game Center in your game allows players to:" + }, + { + "type": "list", + "items": [ + "Discover new games their friends are playing.", + "Seamlessly invite friends to play.", + "See the latest activity from their games across the system, in the Apple Games app, the App Store, notifications, and more." + ] + }, + { + "type": "paragraph", + "text": "By enabling the player activities listed above, supporting Game Center also helps surface your game to more players across Apple platforms." + }, + { + "type": "paragraph", + "text": "You can add Game Center into your game using the GameKit framework, which provides a full-featured UI that makes it easy for players to access and view their Game Center data within your game. Alternatively, you can also use GameKit to present this data within your own custom UI. For developer guidance, see GameKit." + } + ] + }, + { + "heading": "Accessing Game Center", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "To provide the best Game Center experience for your players, begin by determining whether the player is signed in to their Game Center account on the system when they launch your game. If they aren’t, initialize the player with Game Center at that time. This provides the most seamless user experience, and maximizes discovery opportunities for your game, such as in the Top Played chart and in social recommendations through players’ friends." + } + ] + }, + { + "heading": "Integrating the access point", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The Game Center access point is an Apple-designed UI element that lets players view their Game Center profile and information without leaving your game. For developer guidance, see Adding an access point to your game." + }, + { + "type": "paragraph", + "text": "In iOS, iPadOS, and macOS the access point leads players to the Game Overlay, a system overlay that allows players to view their progress and start game activities." + }, + { + "type": "paragraph", + "text": "In visionOS and tvOS, the access point leads players to the in-game dashboard, a full-screen view of a player’s Game Center activity that appears on top of your game." + }, + { + "type": "paragraph", + "text": "Display the access point in menu screens. Consider adding the access point to the main menu or the settings area of your game. Avoid displaying the access point during active gameplay or in temporary splash screens, cinematic flows, or tutorials that might precede your game’s main menu screen." + }, + { + "type": "paragraph", + "text": "Avoid placing controls near the access point. You can choose to present the access point at any of the four corners of the screen in a fixed position. Remember that the access point has both a collapsed and expanded version, so check whether the access point overlaps any important UI and controls and adjust your layout accordingly." + }, + { + "type": "note", + "text": "NoteIn visionOS, the locations of the access point vary based on game type, such as immersive or volume-based. For developer guidance, see Adding an access point to your game." + }, + { + "type": "paragraph", + "text": "Consider pausing your game while the Game Overlay or dashboard is present. Pausing your game can help players view their Game Center information without feeling like the game is continuing without them." + } + ] + }, + { + "heading": "Using custom UI", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Your game can include custom links into the Game Overlay (in iOS, iPadOS, macOS) or the dashboard (in visionOS and tvOS). Your custom UI can deep-link into specific areas within both such as leaderboards or a player’s Game Center profile." + }, + { + "type": "paragraph", + "text": "Use the artwork Game Center provides in custom links. When referencing Game Center features in custom UI, use the official artwork from Apple Design Resources. Preserve the appearance of this artwork and don’t adjust the dimensions or visual effects." + }, + { + "type": "paragraph", + "text": "Use the correct terminology in custom links. The following table describes how to use Game Center terminology correctly so that you can avoid confusing players in custom UI." + }, + { + "type": "table", + "rows": [ + [ + "Term", + "Incorrect terms", + "Localization" + ], + [ + "Game Center", + "GameKit, GameCenter, game center", + "Use the system-provided translation of Game Center" + ], + [ + "Game Center Profile", + "Profile, Account, Player Info", + "Use the system-provided translation of Game Center and localize Profile" + ], + [ + "Achievements", + "Awards, Trophies, Medals", + "" + ], + [ + "Leaderboards", + "Rankings, Scores, Leaders", + "" + ], + [ + "Challenges", + "Competitions", + "" + ], + [ + "Add Friends", + "Add, Add Profiles, Include Friends", + "" + ] + ] + } + ] + }, + { + "heading": "Achievements", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Achievements give players an added incentive to stay engaged with your game. Game Center achievements appear in a collectible card format that highlights the player’s progress and showcases your artwork. For developer guidance, see Rewarding players with achievements." + }, + { + "type": "paragraph", + "text": "Achievements overview" + }, + { + "type": "paragraph", + "text": "Achievement detail" + } + ] + }, + { + "heading": "Integrating achievements into your game", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Align with Game Center achievement states. Game Center defines four achievement states: locked, in-progress, hidden, and completed. The system groups achievements by completion status, displaying completed achievements in the Completed group and all other achievements in the Locked group. When you map your achievements to the four Game Center achievement states, you give players a consistent experience and you help them see at a glance the types of achievements your game offers." + }, + { + "type": "paragraph", + "text": "Determine a display order. The order in which you upload achievements is the order in which they appear, so consider the order you want before uploading files. For example, you might want your achievements to appear in an order that corresponds to the most common path through your game." + }, + { + "type": "paragraph", + "text": "Be succinct when describing achievements. The achievement card limits the title and description to two lines each. If your title or description wraps beyond two lines, the card truncates the text. Use title-style capitalization for the achievement title and sentence-style capitalization for the description." + }, + { + "type": "paragraph", + "text": "Give players a sense of progress. When you use progressive achievements, the system displays player progress and provides encouraging messages like “Youʼre more than halfway to completing Great Lakes Freighter in The Coast. Keep going!” to help motivate players to complete them." + } + ] + }, + { + "heading": "Creating achievement images", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Design rich, high-quality images that help players feel rewarded. Achievements are a prominent feature in Game Center UI, so it’s essential to design high-quality assets that catch the eye and encourage players to return to your game. Avoid reusing the same asset to represent more than one achievement. If you don’t provide an asset for an achievement, the card shows a placeholder image instead." + }, + { + "type": "paragraph", + "text": "Create artwork in the appropriate size and format. The system applies a circular mask to your achievement image, so be sure to keep content centered. Use the following specifications to create images." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "PNG, TIF, or JPG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "512x512 pt (1024x1024 px @2x)" + ], + [ + "Mask diameter", + "512 pt (1024 px @2x)" + ] + ] + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "PNG, TIF, or JPG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "320x320 pt (640x640 px @2x)" + ], + [ + "Mask diameter", + "200 pt (400 px @2x)" + ] + ] + } + ] + }, + { + "heading": "Leaderboards", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Leaderboards are a great way to encourage friendly competition within your game. When you adopt Game Center, players can easily check their ranking against friends and global players as well as receive notifications when their friends challenge them or pass their score on a leaderboard. You can take advantage of the system-designed UI or present leaderboard information within custom UI. For developer guidance, see Encourage progress and competition with leaderboards." + }, + { + "type": "paragraph", + "text": "Leaderboards overview" + }, + { + "type": "paragraph", + "text": "Leaderboard detail" + }, + { + "type": "paragraph", + "text": "Choose a leaderboard type. Game Center supports two types of leaderboards: classic and recurring." + }, + { + "type": "list", + "items": [ + "A classic leaderboard tracks a player’s best all-time score. Classic leaderboards are always active with no ending. The following are examples of goals you might include in a classic leaderboard:Strive for the most perfect score in a rhythm game.Collect the most coins in a single dungeon run.Achieve the longest continuous time in an endless runner.", + "A recurring leaderboard resets based on a time interval you define, such as every week or every day. Recurring leaderboards can increase engagement by giving players more chances to take the lead. The following are examples of features that work well with recurring leaderboards:Daily rotating puzzlesSeasonal or holiday-themed eventsWeekly leaderboards for different battle modes" + ] + }, + { + "type": "paragraph", + "text": "Take advantage of leaderboard sets for multiple leaderboards. Leaderboard sets are an organization system that can make it easier for players to find the board they’re looking for. Consider grouping leaderboard sets by themes or gameplay experiences, such as:" + }, + { + "type": "list", + "items": [ + "Difficulty modes (Easy, Standard, Hard)", + "Activity types (Combat, Crafting, Farming)", + "Genres and themes (Disco, Pop, Rock)" + ] + }, + { + "type": "paragraph", + "text": "Add leaderboard images. Leaderboard artwork gives you another opportunity to reinforce your game’s visual aesthetic. Aim to create a unique image for each leaderboard in your game that reflects and showcases the gameplay involved in leaderboard ranking. Leaderboards appear across the system, promoting ways for players to engage and compete with friends, and having compelling images helps attract players and gives them a sense of the experience." + }, + { + "type": "paragraph", + "text": "For games that run in iOS, iPadOS, and macOS, use a single image for your leaderboard image. For games that run in tvOS, provide a set of images that animate when the artwork is in focus. To learn more about focus effects, see Focus and selection. For help creating focusable images, download the tvOS template from Apple Design Resources. Use the following specifications to create leaderboard artwork." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "JPEG, JPG, or PNG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "512x512 pt (1024x1024 px @2x)" + ], + [ + "Cropped area", + "512x312 pt (1024x624 px @2x)" + ] + ] + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "PNG, TIF, or JPG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "659x371 pt (1318x742 px @2x)" + ], + [ + "Focused size", + "618x348 pt (1236x696 px @2x)" + ], + [ + "Unfocused size", + "548x309 pt (1096x618 px @2x)" + ] + ] + }, + { + "type": "note", + "text": "NoteBe mindful of how cropping might affect your leaderboard artwork. In iOS, iPadOS, and macOS, the system crops artwork for leaderboards that are part of a leaderboard set. In tvOS, the focus effect on leaderboard artwork may crop your images at the edges of some layers. Make sure your primary content stays comfortably visible in both these scenarios." + } + ] + }, + { + "heading": "Challenges", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Challenges turn single player activities into multiplayer experiences with friends. Challenges are built on top of leaderboards and allow players to connect with their friends and participate in competitions with time limits. For developer documentation, see Creating engaging challenges from leaderboards." + }, + { + "type": "paragraph", + "text": "Challenges overview" + }, + { + "type": "paragraph", + "text": "Challenge detail" + }, + { + "type": "paragraph", + "text": "Create engaging challenges. Challenges are great for short, skill-based gameplay activities that have a clear way of gauging players’ accomplishments. Create challenges that take 1-5 minutes to play, with gameplay that players can complete individually. Examples of compelling challenges are:" + }, + { + "type": "list", + "items": [ + "Complete the fastest lap in a racing level.", + "Defeat the most enemies in a single round.", + "Solve a daily puzzle with the fewest mistakes." + ] + }, + { + "type": "paragraph", + "text": "Avoid creating challenges that track overall progress or personal best scores. These can give regular players an unfair advantage. Instead, track players’ most recent score after each attempt at your challenge. This helps keep your challenge motivating by placing all players on a level playing field." + }, + { + "type": "paragraph", + "text": "Make it easy to jump into your challenge. Players can access challenges through invitation links, the Game Overlay, or in the Games app in iOS, iPadOS, and macOS. Always deep-link to the exact mode or level where your challenge begins, and help first-time players complete any initial onboarding before beginning the challenge. For example, if your game requires a tutorial level to understand basic controls, launch the player into the tutorial first and present UI that lets them know your game automatically jumps into the challenge afterward." + }, + { + "type": "paragraph", + "text": "Create high-quality artwork that encourages players to engage with your challenges. The system shows your challenge’s artwork in the Game Overlay, Games app, and in the preview of an invitation link. Avoid placing the primary content of your artwork in an area where the challenge’s title and description might cover it. If you need to use text in your challenge image, provide the appropriate localized versions through App Store Connect or Xcode. Use the following specifications to create challenge artwork." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "JPEG, JPG, or PNG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "1920x1080 pt (3840x2160 px @2x)" + ], + [ + "Cropped area", + "1465x767 pt (2930x1534 px @2x)" + ] + ] + } + ] + }, + { + "heading": "Multiplayer activities", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Game Center supports both real-time and turn-based multiplayer activities that make it easy to connect players with friends or other players. Players can access multiplayer gameplay through party codes, the Game Overlay, the dashboard, or in the Games app. For developer documentation, see Creating activities for your game." + }, + { + "type": "paragraph", + "text": "Multiplayer levels overview" + }, + { + "type": "paragraph", + "text": "Multiplayer level detail" + }, + { + "type": "paragraph", + "text": "Use party codes to invite players to multiplayer activities. Game Center party codes are a great way to coordinate real-time multiplayer sessions whether you use Game Center matchmaking and networking facilities or provide your own. Game Center generates alpha-numeric party codes that are typically eight characters long, such as “2MP4-9CMF.” When integrating party codes into your multiplayer games, consider the following guidelines for the best player experience:" + }, + { + "type": "list", + "items": [ + "Allow players to join gameplay late, leave early, and return later.", + "Provide a way for players to view the current party code in your game.", + "Allow players to enter a party code manually." + ] + }, + { + "type": "paragraph", + "text": "Support multiplayer activities through in-game UI. The Game Overlay and Game Center dashboard help players find other people for a multiplayer match without leaving your game. Game Center’s default multiplayer interface lets a player invite nearby or recent players, Game Center friends, and contacts. You can also choose to present multiplayer functionality within your custom UI. For developer guidance, see Finding multiple players for a game." + }, + { + "type": "paragraph", + "text": "Provide engaging activity artwork. Players see the preview image for a multiplayer activity throughout the system, such as in a party code, the Games app, or in-game UI. Use the following specifications to create your artwork." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Format", + "JPEG, JPG, or PNG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ], + [ + "Image size", + "1920x1080 pt (3840x2160 px @2x)" + ], + [ + "Cropped area", + "1465x767 pt (2930x1534 px @2x)" + ] + ] + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or visionOS." + } + ] + }, + { + "heading": "tvOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Display an optional image at the top of the dashboard. In tvOS, you can add an additional piece of artwork to the dashboard to highlight your game’s aesthetic. Use a simple, easily recognizable image that looks great at a distance. Consider using your game’s logo or word mark; however, don’t use your app icon for this image. Use the following specifications to create a dashboard image." + }, + { + "type": "table", + "rows": [ + [ + "Attribute", + "Value" + ], + [ + "Image size", + "600x180 pt (1200x360 px @2x)" + ], + [ + "Format", + "PNG, TIF, or JPG" + ], + [ + "Color space", + "sRGB or P3" + ], + [ + "Resolution", + "72 DPI (minimum)" + ] + ] + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Be aware of Game Center support on watchOS. While GameKit features and API are available for watchOS games, keep in mind that there’s no system-supported Game Center UI that you can invoke on watchOS. Instead, Game Center content for watchOS games appears on a connected iPhone." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Designing for games" + }, + { + "type": "paragraph", + "text": "Game controls" + }, + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "GameKit" + }, + { + "type": "paragraph", + "text": "Creating activities for your game" + }, + { + "type": "paragraph", + "text": "Creating engaging challenges from leaderboards" + }, + { + "type": "paragraph", + "text": "Create games for Apple platforms" + }, + { + "type": "paragraph", + "text": "Game Porting Toolkit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Added guidance for new challenges and multiplayer activities, and considerations for the Apple Games app and Game Overlay. Updated guidance and specifications for activity preview images." + ], + [ + "February 2, 2024", + "Added links to developer guidance on using the access point and dashboard in a visionOS game." + ], + [ + "September 12, 2023", + "Added artwork for the iOS achievement layout." + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Accessing Game Center", + "url": "/design/human-interface-guidelines/game-center#Accessing-Game-Center" + }, + { + "title": "Integrating the access point", + "url": "/design/human-interface-guidelines/game-center#Integrating-the-access-point" + }, + { + "title": "Using custom UI", + "url": "/design/human-interface-guidelines/game-center#Using-custom-UI" + }, + { + "title": "Achievements", + "url": "/design/human-interface-guidelines/game-center#Achievements" + }, + { + "title": "Integrating achievements into your game", + "url": "/design/human-interface-guidelines/game-center#Integrating-achievements-into-your-game" + }, + { + "title": "Creating achievement images", + "url": "/design/human-interface-guidelines/game-center#Creating-achievement-images" + }, + { + "title": "Leaderboards", + "url": "/design/human-interface-guidelines/game-center#Leaderboards" + }, + { + "title": "Focus and selection", + "url": "/design/human-interface-guidelines/focus-and-selection" + }, + { + "title": "Challenges", + "url": "/design/human-interface-guidelines/game-center#Challenges" + }, + { + "title": "Multiplayer activities", + "url": "/design/human-interface-guidelines/game-center#Multiplayer-activities" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/game-center#Platform-considerations" + }, + { + "title": "tvOS", + "url": "/design/human-interface-guidelines/game-center#tvOS" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/game-center#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/game-center#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/game-center#Related" + }, + { + "title": "Designing for games", + "url": "/design/human-interface-guidelines/designing-for-games" + }, + { + "title": "Game controls", + "url": "/design/human-interface-guidelines/game-controls" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/game-center#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/game-center#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/game-center#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Generative AI", + "url": "https://developer.apple.com/design/human-interface-guidelines/generative-ai", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Generative artificial intelligence uses machine learning models to create and transform text, images, and other content. Use it to offer novel, delightful features that help people express themselves creatively, communicate effectively, and complete tasks more easily. For instance, generative AI can enable people to edit text, create imaginative stories and images, or interact with a character in a game that uses AI-generated dialog." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Design your experience responsibly. Responsible AI is the intentional design and development of AI features that considers their direct and indirect impacts on people, systems, and society. With generative AI, it’s often easy to quickly prototype an exciting new feature for your app, yet challenging to create a robust experience that works in all real-world situations. Unlike classic programming, small changes to inputs (or even the same input, when given multiple times) often produce very different outcomes with generative AI. You also can’t always anticipate what requests people will make and how the AI will respond. Orient your design process around crafting AI experiences that are inclusive, designed with care, and protect privacy." + }, + { + "type": "paragraph", + "text": "Keep people in control. While AI can manipulate and create content, respect people’s agency and ensure they remain in charge of decision making and the overall experience. Honor their requests when in scope and the expected output is clear, and handle sensitive content carefully. Give them the ability to dismiss new content they don’t want, and revert or retry content transformations or other actions they don’t agree with. Clearly identify when and where you use AI." + }, + { + "type": "paragraph", + "text": "Ensure an inclusive experience for all. AI models learn from data and tend to favor the most common information. This may lead to harmful, unintended biases and stereotypes. Take extra care when designing your AI feature to consider how assumptions and personal attributes might impact the feature you have in mind. For example, if you generate images or descriptions of people, ask people to provide the information needed for the feature to work well rather than solely inferring personal or cultural characteristics. Seek clarity before making assumptions that may lead to common stereotypes, such as about gender identities or relationship types. Test your feature across a diverse set of people to identify and correct stereotypes, and ensure inclusive results. For guidance, see Inclusion and Accessibility." + }, + { + "type": "paragraph", + "text": "Design engaging and useful generative features. Generative AI is a powerful tool, but it’s not the right solution for every situation. Offer generative features when and where they provide clear and specific value, like time savings, improved communication, or enhanced creativity." + }, + { + "type": "paragraph", + "text": "Ensure a great experience even when generative features aren’t available or people opt not to use them. In some cases, generative AI may be essential to an experience, and there’s no reasonable non-AI substitute. In other cases, AI may play a complementary role that enhances your app’s core functionality, but isn’t critical for people achieving their goals. For example, Genmoji offers a fun way to create new, original emoji, but people can still use regular emoji too. The Apple Intelligence summarization feature makes catching up with notifications faster, but people can still read notifications without it. When possible, consider offering a non-AI fallback so people can always enjoy your app or game." + } + ] + }, + { + "heading": "Transparency", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Communicate where your app uses AI. Letting people know when and where your app uses AI sets expectations and gives people the opportunity to knowingly choose to use an AI-powered feature. Never trick someone into thinking they’re interacting with or viewing content authored by a human if they’re actually interacting with AI. Ensure your approach to disclosure aligns with any regulations in the regions where you offer your app." + }, + { + "type": "paragraph", + "text": "Set clear expectations about what your AI-powered feature can and can’t do. Clarifying your experience’s capabilities and limitations helps people establish a mental model of your feature. For example, when you introduce a feature, you might offer a brief tutorial. For open-ended features like a search bar or generation prompt, consider offering curated suggestions that make it easy to get started. If your feature has known limitations, let people know up front, show them how to get good results, and explain why when inferior results occur. For guidance, see Limitations." + } + ] + }, + { + "heading": "Privacy", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer on-device processing. Depending on your needs, you may be able to get great responses using on-device models, which prevent people’s information from leaving the device. For example, you may choose to use the on-device models available through the Apple Foundation Models framework. On-device models may also respond quicker than server-based models, and are available even when the device is offline. Server-based models are usually good options in situations that need larger, powerful models that require more memory and power than is typically available on a person’s device. Always consider privacy and user experience tradeoffs when selecting a model type. If you’re using server-based processing, process as much information as you can locally first and minimize what’s shared. Make sure people know if their information may be sent to a server, can see what’s being shared, and understand what data may be stored off-device or even used for training." + }, + { + "type": "paragraph", + "text": "Ask permission before using personal information and usage data. Some interactions with an AI model may involve sensitive information, like personal details, messages, photos, and feature usage information. After obtaining permission, use the minimum data you need and always offer a clear way to opt out of its use. If you need sensitive data for model improvement or storage, get explicit permission and handle it with care. If you share data with third parties, understand their approach to privacy. Be aware that model outputs can inadvertently contain sensitive information. Note that apps for kids have stricter rules and laws around what data you can use. For guidance, see Requesting permission." + }, + { + "type": "paragraph", + "text": "Clearly disclose how your app and its model use and store personal information. People are more likely to be comfortable sharing data when they understand how it’s used. Empower people to make an informed decision about what data they share with your AI model. When asking for permission to use someone’s information, explain the benefits in a way that’s concise, specific, and easy to understand. Articulate whether your model uses personal information for training and improvement." + } + ] + }, + { + "heading": "Models and datasets", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Thoughtfully evaluate model capabilities. There are different types of generative models, some of which possess general knowledge, while others are trained for specific tasks. It’s important to understand the capabilities of any model you consider. As early as you can, get a hands-on look at the models and data available to help orient your design. Keep in mind that some model types may be unavailable to people in certain situations due to factors like device compatibility, network access, and battery level. For example, the Foundation Models framework requires a compatible device with Apple Intelligence turned on." + }, + { + "type": "paragraph", + "text": "Be intentional when choosing or creating a dataset. Whether you’re training a model from scratch or customizing an existing model, the data you choose greatly impacts the model’s behavior. When you teach and evaluate your AI model, choose datasets that include a diverse range of subject matter representations. Learn where your data comes from and how it was gathered. Ensure you have relevant licenses for all data you don’t personally own, and offer appropriate choices when using people’s data. Most datasets gathered from the real world are imperfect, so allow time for testing and evaluation to proactively mitigate bias and misinformation that a model might learn and replicate." + } + ] + }, + { + "heading": "Inputs", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Guide people on how to use your generative feature. Consider how to steer and educate people toward producing great results. One technique is to offer diverse, predefined example inputs that hint at what’s possible for a feature." + }, + { + "type": "paragraph", + "text": "Raise awareness about and minimize the chance of hallucinations. When a generative model is unsure how to respond to a request, it may produce content that seems plausible but is made up. These hallucinations can misinform people because the model may convincingly present the information as factual, even when it’s not. Generative models sometimes get details wrong, like dates of important events or information about people, so it’s important to clearly communicate that AI-generated content may contain errors. You can minimize the chance of hallucinations and limit their impact by carefully scoping what you ask a model to generate. Avoid requesting factual information unless you’re confident the model has access to verified and up-to-date information for the task. Avoid using AI-generated content in situations where a possible hallucination could misinform and harm someone." + }, + { + "type": "paragraph", + "text": "Consider consequences and get permission before performing destructive or potentially problematic tasks. Before performing a task, consider whether a mistake or the inability to reverse the action might cause more work or stress for people. Avoid automating destructive actions, like deleting photos, and actions that are hard to undo, like making a purchase on a person’s behalf. Generally, ask for confirmation before performing a significant action on someone’s behalf. Keep in mind that certain situations may be prohibited or have extra rules. Review and adhere to model-specific usage policies, as well as government and regulatory AI policy as it applies to each locale in which the generative features will be available." + } + ] + }, + { + "heading": "Outputs", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Help people improve requests when blocked or undesirable results occur. Minimize scoped or blocked output by coaching people how to be more successful next time. For example, if prompted to generate harmful content, Image Playground says that it’s “Unable to use that description.” When possible, consider offering example requests that might lead to better results." + }, + { + "type": "paragraph", + "text": "Reduce unexpected and harmful outcomes with thoughtful design and thorough testing. People generally use apps with good intentions, but harmful outcomes can still arise from both accidental and purposeful misuse, and when responding to potentially sensitive topics. It may not be possible to mitigate every harmful scenario, but taking a proactive approach to identify risks, devise policies to address them, and evaluate features can help minimize the chance of misuse and harm. Consider ways people might interact with your feature and test those scenarios. Challenge your policies and expected use cases. See what happens when requests are out-of-scope, unrelated to the app experience you designed, and not well-represented by the model’s training data. Try requests that are poorly phrased, vague, or ambiguous; include personal, sensitive, or controversial topics; and encourage harmful or incorrect results. Use what you learn to improve your model, inform prevention, and respond thoughtfully." + }, + { + "type": "paragraph", + "text": "Strive to avoid replicating copyrighted content. Large AI models are trained using vast datasets from the internet and other sources. This means most generative models are familiar with and can unintentionally produce content similar to published work, including copyrighted content. You can reduce the likelihood of copyright infringement by building upon existing models that already protect against this, and by carefully curating inputs. For example, you might let people choose from a set of pre-approved prompts. You could also explicitly tell the model to avoid mimicking certain content or styles." + }, + { + "type": "paragraph", + "text": "Factor processing time into your design. Latency is how much time it takes for a model to produce an output. Non-generative models, such as people tracking in ARKit and the Vision machine learning framework, typically have low latency and are suitable to run in real-time on camera feeds. Generative models typically take longer to produce a result, so design a loading experience or generate in the background while a person uses another part of the app. For guidance, see Loading." + }, + { + "type": "paragraph", + "text": "Consider offering alternate versions of results. Depending on the design of your feature, it might work best to present a single result or multiple meaningfully different results from which people can choose. Offering people a choice can give them a greater sense of control and help bridge the gap between the model’s interpretation and what someone actually wants. For example, Image Playground can generate multiple images that represent a person, allowing someone to pick the one they prefer. For guidance, see Multiple options." + } + ] + }, + { + "heading": "Continuous improvement", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Consider ways to improve your model over time. You may want to update your model to adapt to people’s behavior, respond to feedback, include new data, and leverage enhanced capabilities. You can make some improvements, such as updating a list of blocked words, frequently and independent of the app development cycle, and you can plan significant improvements and new features around regular app updates. Plan for fine-tuning, retesting, and prompt engineering when updating to a newer, more capable base model. If you train your own model, retrain with additional data and fine-tune to improve performance. Thoroughly test and refine all model updates to identify and correct unexpected behavior." + }, + { + "type": "paragraph", + "text": "Let people share feedback on outputs. Feedback can help you identify and respond to unexpected outcomes and new potential issues that arise despite thorough testing. Feedback also gives people a way to celebrate what they like best about your AI experience and report concerns when outputs don’t match their expectations. Establish trust by taking feedback seriously and resolving issues quickly. Always make providing feedback voluntary. Respect people’s time by placing a feedback affordance in a clear location that doesn’t interrupt the experience. Consider offering a quick and easy way to give positive and negative feedback, like simple thumbs-up and thumbs-down buttons. You might also offer a way to share detailed feedback for complicated issues. For guidance, see Explicit feedback and Implicit feedback." + }, + { + "type": "paragraph", + "text": "Design flexible, adaptable features. Generative AI is a rapidly advancing technology, and models and their resource needs are constantly evolving. Consider ways your app or game can adapt as capabilities and models improve. For example, you may want to separate your model from your user experience so you can swap out the model for other models over time. Lay a foundation that allows for future adjustments like this, while still offering the same great user experience." + } + ] + }, + { + "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": "Machine learning" + }, + { + "type": "paragraph", + "text": "Inclusion" + }, + { + "type": "paragraph", + "text": "Accessibility" + }, + { + "type": "paragraph", + "text": "Privacy" + }, + { + "type": "paragraph", + "text": "Loading" + }, + { + "type": "paragraph", + "text": "Acceptable Use Requirements for the Foundation Models Framework" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Intelligence and machine learning" + }, + { + "type": "paragraph", + "text": "Foundation Models" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "machine learning", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/generative-ai#Best-practices" + }, + { + "title": "Inclusion", + "url": "/design/human-interface-guidelines/inclusion" + }, + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Transparency", + "url": "/design/human-interface-guidelines/generative-ai#Transparency" + }, + { + "title": "Limitations", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Limitations" + }, + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/generative-ai#Privacy" + }, + { + "title": "Requesting permission", + "url": "https://developer.apple.com/design/human-interface-guidelines/privacy#Requesting-permission" + }, + { + "title": "Models and datasets", + "url": "/design/human-interface-guidelines/generative-ai#Models-and-datasets" + }, + { + "title": "Inputs", + "url": "/design/human-interface-guidelines/generative-ai#Inputs" + }, + { + "title": "Outputs", + "url": "/design/human-interface-guidelines/generative-ai#Outputs" + }, + { + "title": "Loading", + "url": "/design/human-interface-guidelines/loading" + }, + { + "title": "Multiple options", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Multiple-options" + }, + { + "title": "Continuous improvement", + "url": "/design/human-interface-guidelines/generative-ai#Continuous-improvement" + }, + { + "title": "Explicit feedback", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Explicit-feedback" + }, + { + "title": "Implicit feedback", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Implicit-feedback" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/generative-ai#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/generative-ai#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/generative-ai#Related" + }, + { + "title": "Machine learning", + "url": "/design/human-interface-guidelines/machine-learning" + }, + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/privacy" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/generative-ai#Videos" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/generative-ai#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/generative-ai#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "HealthKit", + "url": "https://developer.apple.com/design/human-interface-guidelines/healthkit", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you support HealthKit in your app, you can ask people for permission to access and update their health information." + }, + { + "type": "important", + "text": "ImportantIf your app doesn’t provide health and fitness functionality, don’t request access to people’s private health data." + }, + { + "type": "paragraph", + "text": "For example, a nutrition app might ask for permission to retrieve people’s weight and activity data, so it can define calorie consumption goals and make dietary recommendations. In this scenario, the nutrition app could also send data — such as the calories that people log — to HealthKit, which can include the data in its global progress metrics." + }, + { + "type": "paragraph", + "text": "For developer guidance, see HealthKit." + } + ] + }, + { + "heading": "Privacy protection", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You must request permission to access people’s data, and you must take all necessary steps to protect that data. After you receive permission, it’s essential to maintain people’s trust by clearly showing them how you use their data. For developer guidance, see Protecting user privacy." + }, + { + "type": "paragraph", + "text": "Provide a coherent privacy policy. During the app submission process, you must provide a URL to a clearly stated privacy policy, so that people can view the policy when they click the link in the App Store page for your app. For developer guidance, see App Information > App Store Connect Help." + }, + { + "type": "paragraph", + "text": "Request access to health data only when you need it. It makes sense to request access to weight information when people log their weight, for example, but not immediately after your app launches. When your request is clearly related to the current context, you help people understand your app’s intentions. Also, people can change the permissions they grant, so your app needs to make a request every time it needs access. For developer guidance, see requestAuthorization(toShare:read:completion:)." + }, + { + "type": "paragraph", + "text": "Clarify your app’s intent by adding descriptive messages to the standard permission screen. People expect to see the system-provided permission screen when asked to approve access to health data. Write a few succinct sentences that explain why you need the information and how people can benefit from sharing it with your app. Avoid adding custom screens that replicate the standard permission screen’s behavior or content." + }, + { + "type": "paragraph", + "text": "Manage health data sharing solely through the system’s privacy settings. People expect to globally manage access to their health information in Settings > Privacy. Don’t confuse people by building additional screens in your app that affect the flow of health data." + } + ] + }, + { + "heading": "Activity rings", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can enhance your app’s health and wellness offerings by displaying the Activity ring element to show people’s progress toward their Move, Exercise, and Stand goals. The Activity app defines the position and color of each ring, so people are familiar with the element and understand what it means." + }, + { + "type": "paragraph", + "text": "Use Activity rings for Move, Exercise, and Stand information only. Activity rings consistently represent progress in these specific areas. Don’t attempt to replicate or modify Activity rings for other purposes or to display other types of data. Never show Move, Exercise, and Stand progress in another ring-like element." + }, + { + "type": "paragraph", + "text": "Use Activity rings to show progress for a single person. Never use Activity rings to represent data for more than one person, and make sure it’s obvious whose progress is shown, such as by using a label, a photo, or an avatar." + }, + { + "type": "paragraph", + "text": "Don’t use Activity rings for ornamentation. Activity rings provide information to people; they don’t merely embellish your app’s design. Never display Activity rings in labels or background graphics." + }, + { + "type": "paragraph", + "text": "Don’t use Activity rings for branding. Use Activity rings strictly to display Activity progress in your app. Never use Activity rings in your app’s icon or marketing materials." + }, + { + "type": "paragraph", + "text": "Maintain Activity ring and background colors. For a consistent user experience, the visual appearance of Activity rings must always be the same, regardless of the context in which they appear. Never change the look of the rings or background by using filters, changing colors, or modifying opacity. Instead, design the surrounding interface to blend with the rings. For example, enclose the rings within a circle. Always scale the rings appropriately so they don’t seem disconnected or out of place." + }, + { + "type": "paragraph", + "text": "Maintain Activity ring margins. An Activity ring element must include a minimum outer margin of no less than the distance between rings. Never allow other elements to crop, obstruct, or encroach upon this margin or the rings themselves. To display an Activity ring element within a circle, adjust the corner radius of the enclosing view rather than applying a circular mask." + }, + { + "type": "paragraph", + "text": "Differentiate other ring-like elements from Activity rings. Mixing different ring styles can lead to a visually confusing interface. If you must include other rings, use padding, lines, or labels to separate them from Activity rings. Color and scale can also help provide visual separation." + }, + { + "type": "paragraph", + "text": "Provide app-specific information only in Activity notifications. The system already delivers Move, Exercise, and Stand progress updates. Don’t repeat this same information, and never show an Activity ring element in your app’s notifications. It’s fine to reference Activity progress in a notification, but do so in a way that’s unique to your app and doesn’t replicate the same information provided by the system." + }, + { + "type": "paragraph", + "text": "For developer guidance, see HKActivityRingView." + } + ] + }, + { + "heading": "Apple Health icon", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The Apple Health icon shows that an app works with HealthKit and the Health app. The following guidelines help you use the icon correctly. To learn how to refer to HealthKit and the Health app in copy and UI text, see Editorial guidelines; to learn about using the “Works with Apple Health” badge in your marketing communications, see Works with Apple Health." + }, + { + "type": "paragraph", + "text": "Use only the Apple-provided icon. Don’t create your own Apple Health icon design or attempt to mimic any Apple-provided designs. Download the Apple Health app icon from Apple Design Resources." + }, + { + "type": "paragraph", + "text": "Display the name Apple Health close to the Apple Health icon. Displaying both elements near each other reminds people that the icon represents the Health app." + }, + { + "type": "paragraph", + "text": "Display the Apple Health icon consistently with other health-related app icons. In a view that contains other app icons, make the Apple Health icon no smaller than other icons." + }, + { + "type": "paragraph", + "text": "Don’t use the Apple Health icon as a button. Use the icon only to indicate compatibility with the Health app." + }, + { + "type": "paragraph", + "text": "Don’t alter the appearance of the Apple Health icon. Don’t mask the icon to change its corner radius or present it in a circular shape. Don’t add embellishments like borders, color overlays, gradients, shadows, or other visual effects." + }, + { + "type": "paragraph", + "text": "Maintain a minimum clear space around the Apple Health icon of 1/10 of its height. Don’t composite the icon onto another graphic element." + }, + { + "type": "paragraph", + "text": "Don’t use the Apple Health icon within text or as a replacement for the terms Health, Apple Health, or HealthKit. See Editorial guidelines to learn how to properly reference the Health app and HealthKit in text." + }, + { + "type": "paragraph", + "text": "Don’t display Health app images or screenshots. Like all Apple images, these designs are copyrighted and can’t appear in your app or marketing materials. You can include an Activity ring element in your app to display Move, Exercise, and Stand progress; for guidance, see Activity rings." + } + ] + }, + { + "heading": "Editorial guidelines", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Refer to the Health app as Apple Health or the Apple Health app. In your app and marketing text, using Apple Health adds clarity." + }, + { + "type": "paragraph", + "text": "Don’t use the term HealthKit. HealthKit is a developer-facing term that names the framework your app uses to access health data. If you need to explain to people how your app works with their data, use the term the Apple Health app. For example, you might say that your app “works with the Apple Health app” or “uses data from the Apple Health app.”" + }, + { + "type": "paragraph", + "text": "Use correct capitalization when using the term Apple Health. Apple Health is two words, with an uppercase A and uppercase H, followed by lowercase letters. You can display Apple Health entirely in uppercase only when you need to conform to an established typographic interface style, such as in an app that capitalizes all text." + }, + { + "type": "paragraph", + "text": "Use the system-provided translation of Health to avoid confusing people. It’s best to refer to the Apple Health app using the translation that people view on their device." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or watchOS. Not supported in macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Works with Apple Health" + }, + { + "type": "paragraph", + "text": "Activity rings" + }, + { + "type": "paragraph", + "text": "Apple Design Resources" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "HealthKit" + }, + { + "type": "paragraph", + "text": "Protecting user privacy — HealthKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Privacy protection", + "url": "/design/human-interface-guidelines/healthkit#Privacy-protection" + }, + { + "title": "Activity rings", + "url": "/design/human-interface-guidelines/healthkit#Activity-rings" + }, + { + "title": "Apple Health icon", + "url": "/design/human-interface-guidelines/healthkit#Apple-Health-icon" + }, + { + "title": "Editorial guidelines", + "url": "/design/human-interface-guidelines/healthkit#Editorial-guidelines" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/healthkit#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/healthkit#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/healthkit#Related" + }, + { + "title": "Activity rings", + "url": "/design/human-interface-guidelines/activity-rings" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/healthkit#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/healthkit#Videos" + } + ], + "image_count": 0 + }, + { + "title": "HomeKit", + "url": "https://developer.apple.com/design/human-interface-guidelines/homekit", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In iOS, the Home app also lets people manage and configure accessories." + }, + { + "type": "paragraph", + "text": "Your iOS, tvOS, or watchOS app can integrate with HomeKit (and by extension the Home app) to provide a custom or accessory-specific experience. For example, you can:" + }, + { + "type": "list", + "items": [ + "Help people set up, name, and organize their accessories", + "Allow fine-grained accessory configuration and control", + "Provide access to custom accessory features", + "Show people how to create powerful, hands-free automations", + "Provide support" + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see HomeKit. If you’re an MFi licensee, visit the MFi portal for guidance on naming and messaging for accessory packaging." + } + ] + }, + { + "heading": "Terminology and layout", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "HomeKit models the home as a hierarchy of objects and defines a vocabulary of terms that refer to them. The Home app uses the HomeKit object model and terminology to give people intuitive control of accessories by voice, app, and automation." + }, + { + "type": "paragraph", + "text": "It’s crucial for your app to use the terminology and object model that HomeKit defines, so that you can reinforce people’s understanding and make home automation feel approachable." + }, + { + "type": "paragraph", + "text": "In the HomeKit model, the home object is the root of a hierarchy that contains all other objects, such as rooms, accessories, and zones. When there’s more than one home, each home is the root of a different hierarchy." + }, + { + "type": "paragraph", + "text": "Acknowledge the hierarchical model that HomeKit uses. Even if your app doesn’t organize accessories by rooms and zones in its UI, it’s useful to reference the HomeKit model when helping people set up or control their accessories. People need to know where accessories are located so they can use Siri and HomePod to control them by speaking commands like “Siri, turn on the lights upstairs,” or “It’s dark in here.” For more guidance, see Siri interactions." + }, + { + "type": "paragraph", + "text": "Make it easy for people to find an accessory’s related HomeKit details. If your app’s organization is based on accessories, don’t hide other HomeKit information, such as an accessory’s zone or room, in a hard-to-discover settings screen. Instead, consider making the related HomeKit information easily available in an accessory detail view." + }, + { + "type": "paragraph", + "text": "Recognize that people can have more than one home. Even if your app doesn’t support the concept of multiple homes per user, consider providing the relevant home information in an accessory detail view." + }, + { + "type": "paragraph", + "text": "Don’t present duplicate home settings. If your app has a different perspective on the organization of a home, don’t confuse people by asking them to set up all or parts of their homes again or by showing a duplicate settings view. Always defer to the settings people made in the Home app and find an intuitive way to present these details in your UI." + } + ] + }, + { + "heading": "Homes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "HomeKit uses the term home to represent a physical home, office, or other location of relevance to people. One person might have multiple homes." + } + ] + }, + { + "heading": "Rooms", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A room represents a physical room in a home. Rooms don’t have attributes like size or location; they’re simply names that have meaning to people, such as Bedroom or Office. When people assign accessories to a room, they can use voice commands like “Siri, turn on all the lights except the bedroom,” or “Siri, turn on the kitchen and hallway lights.”" + } + ] + }, + { + "heading": "Accessories, services, and characteristics", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The term accessory represents a physical, connected home accessory, like a ceiling fan, lamp, lock, or camera. HomeKit uses category to represent a type of accessory, such as thermostat, fan, or light. Typically, an accessory manufacturer assigns each accessory to a category, but your app can help people make this assignment if necessary. For example, a switch that’s connected to a fan or a lamp needs to be assigned to the same category as the accessory it controls." + }, + { + "type": "paragraph", + "text": "A controllable feature of an accessory, such as the switch on a connected light, is known as a service. Some accessories offer multiple services. For example, a connected garage door might let people control the light and the door separately, or a connected outlet might support separate control of the top outlet and the bottom outlet. Apps don’t use the word service in the UI; instead, they use names that describe the service, such as garage door opener and ceiling fan light. When people use Siri to control the accessories in their homes, they speak the service name, not the accessory name. For more guidance on naming, see Help people choose useful names." + }, + { + "type": "paragraph", + "text": "A characteristic is a controllable attribute of a service. For example, in a ceiling fan, the fan service might have a speed characteristic and the light service might have a brightness characteristic. Apps don’t use the word characteristic in the UI; instead, they use terms that describe the attribute, such as speed and brightness." + }, + { + "type": "paragraph", + "text": "A service group represents a group of accessory services that someone might want to control as a unit. For example, if there’s a floor lamp and two table lamps in one corner of a room, people might assign all three services to a service group named reading lamps. Doing so would let people use the reading lamps service group to control these three lights independently of all other lights in the room." + } + ] + }, + { + "heading": "Actions and scenes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The term action refers to the changing of a service’s characteristic, such as adjusting the speed of a fan or the brightness of a light. People and automation can initiate actions." + }, + { + "type": "paragraph", + "text": "A scene is a group of actions that control one or more services in one or more accessories. For example, people might create a Movie Time scene that lowers the shades and dims the lights in the living room, or a Good Morning scene that turns on the lights, raises the shades, and starts the coffee maker in the kitchen." + }, + { + "type": "tip", + "text": "TipThe HomeKit API uses the term action set instead of scene. In your app’s UI, always use the term scene." + } + ] + }, + { + "heading": "Automations", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Automations cause accessories to react to certain situations, such as when a person’s location changes, a particular time of day occurs, another accessory turns on or off, or a sensor detects something. For example, an automation could turn on the house lights at sunset or when people arrive home." + } + ] + }, + { + "heading": "Zones", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A zone represents an area in the home that contains multiple rooms, such as upstairs or downstairs. Setting up a zone is optional, but doing so lets people control multiple accessories at one time. For example, assigning all downstairs lights to a zone named downstairs lets people use voice commands like “Siri, turn off all the lights downstairs.”" + } + ] + }, + { + "heading": "Setup", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use the system-provided setup flow to give people a familiar experience. The HomeKit setup flow works more quickly than traditional setup flows because it lets people name accessories, join networks, pair with HomeKit, assign room and service categories, and designate favorites in just a few steps. Using the system-provided setup flow lets you concentrate on promoting the custom functionality that makes your accessory unique. For developer guidance, see performAccessorySetup(using:completionHandler:)." + }, + { + "type": "paragraph", + "text": "Provide context to explain why you need access to people’s Home data. Create a purpose string with a phrase that describes why you’re asking for permission to access data, such as “Lets you control this accessory with the Apple Home app and Siri across your Apple devices.”" + }, + { + "type": "paragraph", + "text": "Don’t require people to create an account or supply personal information. Instead, defer to HomeKit for any information you might need. If your app provides additional services that require an account, such as cloud services, make account setup optional and wait until after initial HomeKit setup to offer it." + }, + { + "type": "paragraph", + "text": "Honor people’s setup choices. When people choose to use HomeKit to set up your accessory, don’t force them to set up other platforms during the HomeKit setup flow. A cross-platform setup experience prevents people from using the accessory right away and can cause confusion by presenting too many ways to control the accessory." + }, + { + "type": "paragraph", + "text": "Carefully consider how and when to provide a custom accessory setup experience. Always begin by presenting the system-provided setup flow. Then, after the accessory’s basic functionality is available, offer a custom post-setup experience that highlights the unique features of your accessory and helps people get the most out of it. For example, a light manufacturer’s app could help people create personalized light scenes in their homes using key colors scanned in from photos in their library." + } + ] + }, + { + "heading": "Help people choose useful names", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Suggest service names that suit your accessory. If your app detects when someone creates a suboptimal name for Siri voice controls, recommend alternatives that you know will work well for most people. Never suggest company names or model numbers for use as service names." + }, + { + "type": "paragraph", + "text": "Check that the names people provide follow HomeKit naming rules. If your app lets people rename services, make sure that the new names follow the rules. (The system-provided setup flow automatically checks the original names.) If people enter a name that breaks one or more rules, briefly explain the problem and suggest some alternative names that work. Here are the rules:" + }, + { + "type": "list", + "items": [ + "Use only alphanumeric, space, and apostrophe characters.", + "Start and end with an alphabetic or numeric character.", + "Don’t include emojis." + ] + }, + { + "type": "table", + "rows": [ + [ + "", + "Example service names" + ], + [ + "", + "Reading lamp" + ], + [ + "", + "📚 lamp" + ], + [ + "", + "2nd garage door" + ], + [ + "", + "#2 garage door" + ] + ] + }, + { + "type": "paragraph", + "text": "Help people avoid creating names that include location information. Although it’s natural for someone to use “kitchen light” to name a light in the kitchen, including the room name in the service name can lead to unpredictable results when controlling the accessory by voice. Your app can detect service names that duplicate location information and help people fix them. For example, you might present a post-setup experience that removes the room or zone from a service name and encourages people to assign the accessory to that room or zone instead." + } + ] + }, + { + "heading": "Siri interactions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "HomeKit supports powerful, hands-free control using voice commands. You can help people use Siri to interact with accessories, services, and zones in their home quickly and efficiently." + }, + { + "type": "paragraph", + "text": "Present example voice commands to demonstrate using Siri to control accessories during setup. As soon as people complete the setup of a new accessory, consider using the service name they chose in a few example Siri phrases and encourage people to try them out." + }, + { + "type": "paragraph", + "text": "After setup, consider teaching people about more complex Siri commands. People might not be aware of the broad range of natural language phrases they can use with Siri and HomePod to control their accessories. After setup is complete, find useful places throughout your app to help people learn about these types of commands. For example, in a scene detail view, you could tell people, You can say “Hey Siri, set ‘Movie Time.’”" + }, + { + "type": "paragraph", + "text": "In addition to recognizing the names of homes, rooms, zones, services, and scenes, Siri can also use information such as accessory category and characteristic to identify a service. For example, when people use terms like brighter or dim, Siri recognizes that they’re referring to a service that has a brightness characteristic, even if they don’t speak the name of the service." + }, + { + "type": "paragraph", + "text": "To illustrate the power and flexibility of Siri commands, here are some examples of the types of phrases that people could use to control their accessories." + }, + { + "type": "table", + "rows": [ + [ + "Phrase", + "Siri understands" + ], + [ + "“Turn on the floor lamp”", + "Service (floor lamp)" + ], + [ + "“Show me the entryway camera”", + "Service (entryway camera)" + ], + [ + "“Turn on the light”", + "Accessory category (light)" + ], + [ + "“Turn off the living room light”", + "Room (living room)" + ], + [ + "Accessory category (light)" + ], + [ + "“Make the living room a little bit brighter”", + "Room (living room)" + ], + [ + "Accessory category (implied)" + ], + [ + "Brightness characteristic (brighter)" + ], + [ + "“Turn on the recessed lights”", + "Service group (recessed lights)" + ], + [ + "“Turn off the lights upstairs”", + "Accessory category (lights)" + ], + [ + "Zone (upstairs)" + ], + [ + "“Dim the lights in the bedroom and nursery”", + "Accessory category (lights)" + ], + [ + "Brightness characteristic (dim)" + ], + [ + "Rooms (bedroom, nursery)" + ], + [ + "“Run Good night”", + "Scene (Good night)" + ], + [ + "“Is someone in the living room?”", + "Accessory category (implied)" + ], + [ + "Occupancy detection characteristic (implied)" + ], + [ + "“Is my security system tripped?”", + "Accessory category (security system)" + ], + [ + "“Did I leave the garage door open?”", + "Accessory category (garage door)" + ], + [ + "Open characteristic (open)" + ], + [ + "“Did I forget to turn off the lights in the Tahoe House?”", + "Accessory category (lights)" + ], + [ + "Home (Tahoe House)" + ], + [ + "“It’s dark in here”", + "Current home (here)" + ], + [ + "Current room (via HomePod)" + ], + [ + "Accessory category (implied)" + ] + ] + }, + { + "type": "paragraph", + "text": "Recommend that people create zones and service groups, if they make sense for your accessory. If people might benefit from using context-specific voice commands to control your accessory, suggest these types of interactions and help people set them up. For example, if you provide an accessory such as a light, switch, or thermostat, you could suggest setting up a zone named “upstairs” or a service group named “media center” to support commands like “Siri, turn off the upstairs lights,” or “Siri, activate the media center.”" + }, + { + "type": "paragraph", + "text": "Offer shortcuts only for accessory-specific functionality that HomeKit doesn’t support. HomeKit lets people use ordinary (or natural) language to control accessories without requiring any additional configuration, so you avoid confusing people by offering shortcuts that duplicate HomeKit functionality. Instead, consider offering shortcuts for complementary functionality that your app provides. For example, if people often want to order filters for an air conditioner that you support, you might offer a shortcut like “Order AC filters.” To learn how to provide phrases that people can use for shortcuts, see Shortcuts and suggestions." + }, + { + "type": "paragraph", + "text": "If your app supports both HomeKit and shortcuts, help people understand the difference between these types of voice control. People can get confused if they’re presented with multiple methods of voice control. Be sure you clearly indicate what’s possible with shortcuts, and never encourage people to create a shortcut for a scene or action that HomeKit already supports." + } + ] + }, + { + "heading": "Custom functionality", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Your app is a great place to help people appreciate the unique functionality of your accessory. For example, an app for a light that displays different colors could help people create HomeKit scenes using colors imported from their photos." + }, + { + "type": "paragraph", + "text": "Be clear about what people can do in your app and when they might want to use the Home app. For example, if your app supports only lights, consider encouraging people to create a “Movie Time” scene that not only dims the lights, but also closes the shades, and turns on the TV to a specific input. To do this, first guide people to set up a scene that includes only your accessory’s actions — in this scenario, dimming the lights. Then, your app can suggest that people open the Home app to add their HomeKit-compatible shades and TV to the scene you helped them create. For guidance on how to refer to the Home app, see Referring to HomeKit." + }, + { + "type": "paragraph", + "text": "Defer to HomeKit if your database differs from the HomeKit database. Give people a seamless experience by automatically reflecting changes made in the Home app or in other third-party HomeKit apps. If you must ask people to manage conflicts in your app, present the conflict visually so that they have a clear picture of the choice they need to confirm. For example, if someone changes an accessory’s service name in the Home app, your app can detect this change and could show both names side by side to confirm that the person wants to use the new name in your app, too." + }, + { + "type": "paragraph", + "text": "Ask permission to update the HomeKit database when people make changes in your app. You don’t want to surprise people by changing something in the Home app, so it’s essential to get permission or an indication of intent before you write to the database. In particular, never overwrite HomeKit database settings without a person’s explicit direction." + } + ] + }, + { + "heading": "Cameras", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Your app can display still images or streaming video from a connected HomeKit IP camera." + }, + { + "type": "paragraph", + "text": "Don’t block camera images. It’s fine to supplement the camera’s content with useful features, such as an alert calling attention to potentially interesting activity. However, avoid covering portions of the camera’s images with other content." + }, + { + "type": "paragraph", + "text": "Show a microphone button only if the camera supports bidirectional audio. A nonfunctioning microphone button takes up valuable display space in your app and risks confusing people." + } + ] + }, + { + "heading": "Using HomeKit icons", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use the HomeKit icon in setup or instructional communications related to HomeKit technology." + }, + { + "type": "paragraph", + "text": "In addition, you can use the Apple Home app icon when referencing the Apple Home app or in a button that opens the Apple Home app product page in the App Store." + }, + { + "type": "paragraph", + "text": "Use only Apple-provided icons. Don’t create your own HomeKit or Home app icon design or attempt to mimic the Apple-provided designs. Download HomeKit icons in Resources." + } + ] + }, + { + "heading": "Styles", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "You have several options for displaying the HomeKit icon." + } + ] + }, + { + "heading": "Black HomeKit icon", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the HomeKit icon on white or light backgrounds when other technology icons appear in black." + } + ] + }, + { + "heading": "White HomeKit icon", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the HomeKit icon on black or dark backgrounds when other technology icons appear in white." + } + ] + }, + { + "heading": "Custom color HomeKit icon", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use a custom color when other technology icons appear in the same color." + }, + { + "type": "paragraph", + "text": "Position the HomeKit icon consistently with other technology icons. When other technology icons are contained within shapes, treat the HomeKit icon in the same manner." + }, + { + "type": "paragraph", + "text": "Use the HomeKit icon noninteractively. Don’t use the icon and the name HomeKit in custom interactive elements or buttons. You can use the Apple Home app icon to open the app’s product page in the App Store." + }, + { + "type": "paragraph", + "text": "Don’t use the HomeKit icon within text or as a replacement for the word HomeKit. See Referring to HomeKit to learn how to properly reference HomeKit in text." + }, + { + "type": "paragraph", + "text": "Pair the icon with the name HomeKit correctly. You can show the name below or beside the icon if other technologies are referenced in this way. Use the same font that’s used on the rest of your layout. For related guidance, see Referring to HomeKit." + }, + { + "type": "paragraph", + "text": "Using the icon and name in setup or instructional content" + }, + { + "type": "paragraph", + "text": "Using the icon and name referencing the Apple Home app" + } + ] + }, + { + "heading": "Referring to HomeKit", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Emphasize your app over HomeKit. Make references to HomeKit or Apple Home less prominent than your app name or main identity." + }, + { + "type": "paragraph", + "text": "Adhere to Apple’s trademark guidelines. Apple trademarks can’t appear in your app name or images. In text, use Apple product names exactly as shown on the Apple Trademark List." + }, + { + "type": "list", + "items": [ + "Use Apple product names in singular form only; do not make Apple product names possessive.", + "Don’t translate Apple, Apple Home, HomeKit, or any other Apple trademark.", + "Don’t use category descriptors. For example, say iPad, not tablet.", + "Don’t indicate any kind of sponsorship, partnership, or endorsement from Apple.", + "Attribute Apple, HomeKit, and all other Apple trademarks with the correct credit lines wherever legal information appears within your app.", + "Refer to Apple devices and operating systems only in technical specifications or compatibility descriptions." + ] + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Use HomeKit to turn on your lights from your iPhone or iPad." + ], + [ + "", + "Use HomeKit to turn on your lights from your iOS devices." + ] + ] + }, + { + "type": "paragraph", + "text": "See Guidelines for Using Apple Trademarks." + } + ] + }, + { + "heading": "Referencing HomeKit and the Home app", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Use correct capitalization when using the term HomeKit. HomeKit is one word, with an uppercase H and uppercase K, followed by lowercase letters. Apple Home is two words, with an uppercase A and uppercase H, followed by lowercase letters. If your layout displays only all-uppercase designations, HomeKit or Apple Home can be typeset in all uppercase to match the style of the rest of the layout." + }, + { + "type": "paragraph", + "text": "Don’t use the name HomeKit as a descriptor. Instead use terms like works with, use, supports, or compatible." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "[Brand] lightbulbs work with HomeKit." + ], + [ + "", + "HomeKit-enabled thermostat." + ], + [ + "", + "You can use HomeKit with [App Name]." + ], + [ + "", + "HomeKit lightbulbs." + ] + ] + }, + { + "type": "paragraph", + "text": "Don’t suggest that HomeKit is performing an action or function." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Back door is unlocked with HomeKit." + ], + [ + "", + "HomeKit unlocked the back door." + ] + ] + }, + { + "type": "paragraph", + "text": "Use the name Apple with the name HomeKit, if desired." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Compatible with Apple HomeKit." + ] + ] + }, + { + "type": "paragraph", + "text": "Use the name HomeKit for setup, configuration, and instructions, if desired." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Open HomeKit settings." + ] + ] + }, + { + "type": "paragraph", + "text": "Use the app name Apple Home whenever referring specifically to the app. On the first mention of the app in body copy, use the complete name Apple Home. Subsequent mentions can refer to the Home app." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Open the Apple Home app." + ], + [ + "", + "Open the Apple Home app. Your accessory and room will now appear in the Home app." + ], + [ + "", + "Open Home." + ] + ] + } + ] + }, + { + "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 Design Resources" + }, + { + "type": "paragraph", + "text": "Guidelines for Using Apple Trademarks and Copyrights" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "HomeKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Terminology and layout", + "url": "/design/human-interface-guidelines/homekit#Terminology-and-layout" + }, + { + "title": "home", + "url": "/design/human-interface-guidelines/homekit#Homes" + }, + { + "title": "rooms", + "url": "/design/human-interface-guidelines/homekit#Rooms" + }, + { + "title": "accessories", + "url": "/design/human-interface-guidelines/homekit#Accessories-services-and-characteristics" + }, + { + "title": "zones", + "url": "/design/human-interface-guidelines/homekit#Zones" + }, + { + "title": "Siri interactions", + "url": "/design/human-interface-guidelines/homekit#Siri-interactions" + }, + { + "title": "Help people choose useful names", + "url": "/design/human-interface-guidelines/homekit#Help-people-choose-useful-names" + }, + { + "title": "Actions and scenes", + "url": "/design/human-interface-guidelines/homekit#Actions-and-scenes" + }, + { + "title": "Automations", + "url": "/design/human-interface-guidelines/homekit#Automations" + }, + { + "title": "Setup", + "url": "/design/human-interface-guidelines/homekit#Setup" + }, + { + "title": "Shortcuts and suggestions", + "url": "/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" + }, + { + "title": "Custom functionality", + "url": "/design/human-interface-guidelines/homekit#Custom-functionality" + }, + { + "title": "Referring to HomeKit", + "url": "/design/human-interface-guidelines/homekit#Referring-to-HomeKit" + }, + { + "title": "Cameras", + "url": "/design/human-interface-guidelines/homekit#Cameras" + }, + { + "title": "Using HomeKit icons", + "url": "/design/human-interface-guidelines/homekit#Using-HomeKit-icons" + }, + { + "title": "Styles", + "url": "/design/human-interface-guidelines/homekit#Styles" + }, + { + "title": "Black HomeKit icon", + "url": "/design/human-interface-guidelines/homekit#Black-HomeKit-icon" + }, + { + "title": "White HomeKit icon", + "url": "/design/human-interface-guidelines/homekit#White-HomeKit-icon" + }, + { + "title": "Custom color HomeKit icon", + "url": "/design/human-interface-guidelines/homekit#Custom-color-HomeKit-icon" + }, + { + "title": "Referencing HomeKit and the Home app", + "url": "/design/human-interface-guidelines/homekit#Referencing-HomeKit-and-the-Home-app" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/homekit#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/homekit#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/homekit#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/homekit#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/homekit#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/homekit#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "ID Verifier", + "url": "https://developer.apple.com/design/human-interface-guidelines/id-verifier", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Beginning in iOS 17, you can integrate ID Verifier into your app, letting iPhone read ISO18013-5 compliant mobile IDs and helping you support in-person ID verification. For example, personnel at a concert venue can use your app on iPhone to verify customers’ ages." + }, + { + "type": "paragraph", + "text": "Using ID Verifier has advantages for both customers and organizations." + }, + { + "type": "list", + "items": [ + "Customers only present the minimum data needed to prove their age or identity, without handing over their ID card or showing their device.", + "Apple provides the key components of the certificate issuance, management, and validation process, simplifying app development and enabling a consistent and trusted ID verification experience." + ] + }, + { + "type": "paragraph", + "text": "Depending on the needs of your app, you can use ID Verifier to make the following types of requests:" + }, + { + "type": "list", + "items": [ + "Display Only request. Use a Display Only request to display data — such as a person’s name or age alongside their photo portrait — within system-provided UI on the requester’s iPhone, so the requester can visually confirm the person’s identity. When you make a Display Only request, the customer’s data remains within the system-provided UI and isn’t transmitted to your app. For developer guidance, see MobileDriversLicenseDisplayRequest.", + "Data Transfer request. Use a Data Transfer request only when you have a legal verification requirement and you need to store or process information like a person’s address or date of birth. You must request an additional entitlement to make a Data Transfer request. To learn more, see Get started with ID Verifier; for developer guidance, see MobileDriversLicenseDataRequest and MobileDriversLicenseRawDataRequest." + ] + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Ask only for the data you need. People may lose trust in the experience if you ask for more data than you need to complete the current verification. For example, if you need to ensure that a customer is at least a minimum age, use a request that specifies an age threshold; avoid requesting the customer’s current age or birth date. For developer guidance, see ageAtLeast(_:)." + }, + { + "type": "paragraph", + "text": "If your app qualifies for Apple Business Register, register for ID Verifier to ensure that people can view essential information about your organization when you make a request. Registering for ID Verifier with Apple Business Register lets you provide your official organization name and logo for the system to display on customers’ devices as part of the ID verification UI. To learn if your app qualifies and how to register, see Apple Business Register." + }, + { + "type": "paragraph", + "text": "Provide a button that initiates the verification process. Use a label like Verify Age in a button that performs a simple age check or Verify Identity for a more detailed identity data request. Avoid including a symbol that specifies a particular type of communication, like NFC or QR codes. Never include the Apple logo in any button label." + }, + { + "type": "table", + "rows": [ + [ + "Button type", + "Example usage" + ], + [ + "", + "An app that checks whether people are old enough to attend an event or access a venue, like a concert hall." + ], + [ + "", + "An app that verifies whether specific identity information matches expected values, such as name and birth date when picking up a rental car." + ] + ] + }, + { + "type": "paragraph", + "text": "In a Display Only request, help the person using your app provide feedback on the visual confirmation they perform. For example, when the reader displays the customer’s portrait, you might provide buttons labeled Matches Person and Doesn’t Match Person so your app can receive an approved or rejected value as part of the response." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Business Register" + }, + { + "type": "paragraph", + "text": "IDs in Wallet" + }, + { + "type": "paragraph", + "text": "Identity verification" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adopting the Verifier API in your iPhone app — ProximityReader" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/id-verifier#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/id-verifier#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/id-verifier#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/id-verifier#Related" + }, + { + "title": "Identity verification", + "url": "/design/human-interface-guidelines/wallet#Identity-verification" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/id-verifier#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/id-verifier#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/id-verifier#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "In-app purchase", + "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can also promote and offer in-app purchases directly through the App Store. For developer guidance, see In-App Purchase." + }, + { + "type": "tip", + "text": "TipIn-app purchase and Apple Pay are different technologies that support different use cases. Use in-app purchase to sell virtual goods in your app, such as premium content for your app and subscriptions for digital content. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and event tickets; and for donations." + }, + { + "type": "paragraph", + "text": "Using in-app purchase, there are four types of content you can offer:" + }, + { + "type": "list", + "items": [ + "Consumable content like lives or gems in a game. After purchase, consumable content depletes as people use it, and people can purchase it again.", + "Non-consumable content like premium features in an app. Purchased non-consumable content doesn’t expire.", + "Auto-renewable subscriptions to virtual content, services, and premium features in your app on an ongoing basis. An auto-renewable subscription continues to automatically renew at the end of each subscription period until people choose to cancel it.", + "Non-renewing subscriptions to a service or content that lasts for a limited time, like access to an in-game battle pass. People purchase a non-renewing subscription each time they want to extend their access to the service or content." + ] + }, + { + "type": "paragraph", + "text": "For marketing and business guidance, see In-app purchase and Auto-renewable subscriptions. For information about what you can and can’t sell in your app, including in-app purchase usage requirements and restrictions, see App Review Guidelines." + }, + { + "type": "note", + "text": "NoteFor apps with exceptionally large, frequently updated catalogs of one-time purchases or subscription content from multiple creators, or apps that provide subscriptions with optional add-on content as a single purchase within the app, the Advanced Commerce API allows you to manage your In-App Purchase catalog directly. See the Advanced Commerce API App Store support page for an overview, and see Advanced Commerce API for developer guidance." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people experience your app before making a purchase. People may be more inclined to invest in paid items or features after they’ve enjoyed your app and discovered its value. If you offer auto-renewable subscriptions, consider supporting limited free access to your content; for guidance, see Auto-renewable subscriptions." + }, + { + "type": "paragraph", + "text": "Design an integrated shopping experience. You don’t want people to think they’ve entered a different app when they browse and purchase your digital products. Present products and handle transactions in ways that mirror the style of your app." + }, + { + "type": "paragraph", + "text": "Use simple, succinct product names and descriptions. Titles that don’t truncate or wrap and plain, direct language can help people find products quickly." + }, + { + "type": "paragraph", + "text": "Display the total billing price for each in-app purchase you offer, regardless of type. People need to know the total billing amount for every purchase they consider." + }, + { + "type": "paragraph", + "text": "Display your store only when people can make payments. If someone canʼt make payments — for example, because of parental restrictions — consider hiding your store or displaying UI that explains why the store isnʼt available. For developer guidance, see canMakePayments." + }, + { + "type": "paragraph", + "text": "Use the default confirmation sheet. When someone initiates an in-app purchase, the system displays a confirmation sheet to help prevent accidental purchases. Don’t modify or replicate this sheet." + } + ] + }, + { + "heading": "Supporting Family Sharing", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People can use Family Sharing to share access to their purchased content — such as auto-renewable subscriptions and non-consumable in-app purchases — with up to five additional family members, across all their Apple devices. To encourage people to take advantage of the Family Sharing support you offer, consider the following guidelines." + }, + { + "type": "paragraph", + "text": "Prominently mention Family Sharing in places where people learn about the content you offer. For example, including “Family” or “Shareable” in a subscription or item name and referring to Family Sharing in your sign-up screen can highlight the feature and help people make an informed choice." + }, + { + "type": "paragraph", + "text": "Help people understand the benefits of Family Sharing and how to participate. When you turn on Family Sharing, people can receive notifications about the change, depending on their current settings. For example, an existing subscriber whose sharing setting is turned off (the default) receives a notice from Apple that invites them to share their subscription with family members. Similarly, a family member can get a notification about content that’s being shared with them. (To learn more about the types of notifications people can receive, see Auto-renewable subscriptions.)" + }, + { + "type": "paragraph", + "text": "Aim to customize your in-app messaging so that it makes sense to both purchasers and family members. For example, when a family member views shared content for the first time, you might welcome them with wording like “Your family subscription includes…”." + } + ] + }, + { + "heading": "Providing help with in-app purchases", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Sometimes, people need help with a purchase or want to request a refund. To help make this experience convenient, you can present custom UI within your app that provides assistance, offers alternative solutions, and helps people initiate the system-provided refund flow. For developer guidance, see beginRefundRequest(for:in:); for related guidance specific to auto-renewable subscriptions, see Helping people manage their subscriptions." + }, + { + "type": "paragraph", + "text": "Provide help that customers can view before they request a refund. In addition to including a link to the system-provided refund flow, your custom purchase-help screen can provide assistance you tailor to your app. For example, your custom screen might help people resolve problems with missing purchases, answer frequently asked questions about the in-app purchases you offer, and give people ways to submit feedback or contact you directly for support." + }, + { + "type": "paragraph", + "text": "Use a simple title for the refund action, like “Refund” or “Request a Refund”. The system-provided refund flow makes it clear that people request a refund from Apple, so there’s no need to reiterate this information." + }, + { + "type": "paragraph", + "text": "Help people find the problematic purchase. For each recent purchase you display, include contextual information that helps people identify the one they want. For example, you might display an image of the product — along with its name and description — and list the original purchase date." + }, + { + "type": "paragraph", + "text": "Consider offering alternative solutions. For example, if the customer didn’t receive the item they purchased, you might offer immediate fulfillment or a conciliatory item. Regardless of the alternatives you offer, make it clear that people can still request a refund." + }, + { + "type": "paragraph", + "text": "Make it easy for people to request a refund. Although your purchase-help screen can offer useful information and alternative solutions, make sure this content doesn’t create a barrier to requesting a refund. For example, avoid making people scroll or open another screen to reveal your refund-request button. When people choose your refund-request item, they automatically enter the system-provided refund flow shown below." + }, + { + "type": "paragraph", + "text": "Avoid characterizing or providing guidance on Apple’s refund policies. For example, don’t speculate about whether customers will receive the refund they request. To help people understand the refund-request process, you can provide a link to Request a refund for apps or content that you bought from Apple." + } + ] + }, + { + "heading": "Auto-renewable subscriptions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Call attention to subscription benefits during onboarding. By showing the value of your subscription when people first launch your app, you can educate them on how the app works and help them understand what they’ll gain by subscribing. Include a strong call to action and a clear summary of subscription terms (see Making signup effortless). For related guidance, see Onboarding." + }, + { + "type": "paragraph", + "text": "Offer a range of content choices, service levels, and durations. People appreciate the flexibility to choose the subscription that best meets their needs." + }, + { + "type": "paragraph", + "text": "Consider letting people try your content for free before signing up. Limited free access gives people the opportunity to sample your content and encourages people who already engaged with your content to sign up. For example, you might offer a freemium app, a metered paywall, or a free trial." + }, + { + "type": "paragraph", + "text": "Prompt people to subscribe at relevant times, like when they near their monthly limit of free content. Additionally, consider making it easy for people to subscribe at any time by including prompts at relevant points throughout your app." + }, + { + "type": "paragraph", + "text": "Encourage a new subscription only when someone isn’t already a subscriber. Otherwise, people may believe their existing subscription has lapsed when that’s not actually the case. If you offer the same subscription options in multiple apps or through your website, provide a sign-in option so people don’t think they have to pay multiple times for the same service." + } + ] + }, + { + "heading": "Making signup effortless", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A simple and informative sign-up experience makes it easy for people to act on their interest in your content, whether they’re in your app or viewing your App Store product page." + }, + { + "type": "paragraph", + "text": "Provide clear, distinguishable subscription options. Use short, self-explanatory names that differentiate subscription options from one another, and specify the price and duration for each option. If you offer an introductory price, be sure to list the introductory price, the duration of the offer, and the standard price the customer pays after the offer ends." + }, + { + "type": "paragraph", + "text": "Simplify initial signup by asking only for necessary information. A lengthy sign-up process may lower your subscription conversion rate. Defer asking for additional information until after people have signed up." + }, + { + "type": "paragraph", + "text": "In your tvOS app, help people sign up or authenticate using another device. Instead of asking people to input information in your tvOS app, send a code to another device where they can enter the information you need." + }, + { + "type": "paragraph", + "text": "Give people more information in your app’s sign-up screen. In addition to including links to your Terms of Service and Privacy Policy in your app and App Store metadata, the in-app sign-up screen needs to include:" + }, + { + "type": "list", + "items": [ + "The subscription name, duration, and the content or services provided during each subscription period", + "The billing amount, correctly localized for the territories and currencies where the subscription is available for purchase", + "A way for existing subscribers to sign in or restore purchases" + ] + }, + { + "type": "paragraph", + "text": "For example, the Forest Explorer sign-up screen displays billing totals for monthly, biannual, and annual subscriptions in the most prominent positions. In subordinate positions, it shows breakdowns of the biannual and annual prices, so that people can compare the values and make an informed choice. The sign-up screen also contains a button that existing subscribers can use to restore their purchases." + }, + { + "type": "paragraph", + "text": "Clearly describe how a free trial works. It’s particularly important to make sure people know that when the free trial is over, a payment will be automatically initiated for the next subscription period. For example, the Ocean Journal sign-up screen explicitly states both the duration of the free trial and the amount that’s billed when it ends." + }, + { + "type": "paragraph", + "text": "Include a sign-up opportunity in your app’s settings. App and account settings are common places for people to look for a way to subscribe." + } + ] + }, + { + "heading": "Supporting offer codes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In iOS and iPadOS, subscription offer codes let you use both online and offline channels to give new, existing, and lapsed subscribers free or discounted access to your subscription content. For example, you might provide offer codes through email, give them out at a store or event, or print one on a physical product." + }, + { + "type": "paragraph", + "text": "There are two types of offer codes you can support:" + }, + { + "type": "list", + "items": [ + "A one-time use code is a unique code you generate in App Store Connect. People can redeem a one-time use code through a redemption URL (a shareable link), within your app (when you support redemption), or by entering it in the App Store, where they’re prompted to install your app if they haven’t already. Consider using one-time use codes when your distribution is small or when you need to restrict access to a code.", + "A custom code is a code you create, such as NEWYEAR or SPRINGSALE. People can redeem a custom code through a redemption URL or within your app (when you support redemption). Consider using a custom code when you want to support a large campaign that requires a mass distribution of codes." + ] + }, + { + "type": "paragraph", + "text": "For developer guidance on implementing offer codes, see Offer codes and Set up offer codes. For guidance on other types of offers, see Providing subscription offers." + }, + { + "type": "paragraph", + "text": "Clearly explain offer details. To help people make an informed decision, provide a straightforward and succinct description of your offer in your marketing materials." + }, + { + "type": "paragraph", + "text": "Follow guidelines for creating a custom code. A custom code can contain only alphanumeric ASCII characters. Don’t use special characters, including Chinese and Arabic characters." + }, + { + "type": "paragraph", + "text": "Tell people how to redeem a custom code. Because people can’t redeem a custom code by entering it in their App Store account settings, it’s important to let them know that they can redeem it through a redemption URL or within your app." + }, + { + "type": "paragraph", + "text": "Consider supporting offer redemption within your app. The system automatically provides screens that present the offer-redemption flow, whether people redeem the offer in your app or in the App Store. When you use StoreKit API to let people redeem offer codes within your app, the only custom UI you need to create is one that initiates the system-provided flow. For developer guidance, see presentOfferCodeRedeemSheet(in:) and offerCodeRedemption(isPresented:onCompletion:). There are several natural places to provide this custom UI. For example, you could add a “Redeem Code” button to your paywall, onboarding screens, or your app’s settings screen." + }, + { + "type": "paragraph", + "text": "After people tap your custom redeem button, the system automatically provides a series of code-redemption screens like the ones shown below." + }, + { + "type": "paragraph", + "text": "Supply an engaging and informative promotional image. Creating this optional image can help people understand the value of your content. If you don’t supply a promotional image, the code redemption screens use your app icon by default. To learn more, see Promoting your in-app purchases." + }, + { + "type": "paragraph", + "text": "Help people benefit from unlocked content as soon as they complete the redemption flow. Think about ways to align the post-redemption experience in your app with the subscriber’s new status. For example, you might provide a welcome experience for new subscribers or a brief tour of new features for an existing subscriber who’s unlocked additional functionality. In particular, be prepared to welcome people who subscribe before they open your app for the first time. For example, if you require people to create an account or sign in before they can use your app, make this process as smooth as possible for new subscribers who haven’t experienced it before." + } + ] + }, + { + "heading": "Helping people manage their subscriptions", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Supporting subscription management means people can upgrade, downgrade, or cancel a subscription without leaving your app. Offering subscription management within your app also gives you a natural place to provide help for common subscriber issues and present alternative offers for people to consider." + }, + { + "type": "paragraph", + "text": "Provide summaries of the customer’s subscriptions. In particular, people appreciate viewing the upcoming renewal date without having to search for it. Consider displaying this information in a settings or account screen, near the subscription-management option. For developer guidance, see Product.SubscriptionInfo." + }, + { + "type": "paragraph", + "text": "Consider using the system-provided subscription-management UI. Using StoreKit APIs lets you present a consistent experience that helps people manage or cancel their subscriptions without leaving your app. For developer guidance, see showManageSubscriptions(in:)." + }, + { + "type": "paragraph", + "text": "Consider ways to encourage a subscriber to keep their subscription or resubscribe later. When you use StoreKit APIs, your app is notified when someone chooses to cancel their subscription. In this scenario, you might want to extend a personalized offer as an alternative to cancellation or invite people to describe their reasons for canceling in an exit survey. In addition to giving you insights into various customer problems, survey feedback can also help inform messaging for retention and win-back strategies." + }, + { + "type": "paragraph", + "text": "Always make it easy for customers to cancel an auto-renewable subscription. If the manage subscription action is deep within an app — or hard to recognize — subscribers can feel they’re being discouraged or prevented from canceling." + }, + { + "type": "paragraph", + "text": "Consider creating a branded, contextual experience to complement the system-provided management UI. Within your custom UI, you might offer a popular premium tier or provide personalized suggestions for alternative plans based on what you know about the customer’s preferences or how they use your app. For example, you can create a promotional offer that provides a discounted price for a specific period of time. You might also consider subscription offer codes to help you win back lapsed subscribers and encourage existing subscribers to upgrade." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The sign-up screen in your watchOS app needs to display the same set of information about your subscription options that you display in other versions of your app. For the complete list of required items, see Making signup effortless. The following guidelines can help you design a sign-up screen that feels at home on Apple Watch." + }, + { + "type": "paragraph", + "text": "Clearly describe the differences between versions of your app that run on different devices. If your watchOS app supports different functionality or provides a subset of the content that’s available on other devices, be sure to clarify these differences in your description. Be straightforward about the advantages of accessing subscription content through your watchOS app without implying that the experience is identical to the ones in other versions of your app." + }, + { + "type": "paragraph", + "text": "A description that might lead people to expect access to 90,000 maps on their Apple Watch" + }, + { + "type": "paragraph", + "text": "A description that clarifies how the subscription works on Apple Watch in contrast with other devices" + }, + { + "type": "paragraph", + "text": "Consider using a modal sheet to display the required information. After people respond to your call to action to learn more about your subscription offers, you can use a modal sheet to present all required items in a single view. Even though people must scroll the view to access all the information, displaying it in a modal sheet helps your app UI remain streamlined and concise. Also, a modal sheet’s default Close button makes it easy for people to return to your free content with one tap. If you create a custom sign-up view instead of using a modal sheet, design a complete, efficient flow and include a Close or Cancel button that lets people return to your free content." + }, + { + "type": "paragraph", + "text": "Make subscription options easy to compare on a small screen. People need to understand the terms of each subscription option before they can choose one. Aim to display the duration and discount information for each option in a compact way that’s easy to scan and compare. Here are two ways you might present subscription options in your watchOS app:" + }, + { + "type": "list", + "items": [ + "Display each option in a separate button. Using one button per payment option lets people start the signup process with one tap. In this design, it’s important to lock up each button with its description so that people can see how these elements are related, especially while scrolling.", + "Display a list of options, followed by a button people tap to start the signup process. Using a list to display one option per row gives you a compact design that minimizes scrolling while making subscription choices easy to scan and understand. In this design, the button’s title can update to reflect the chosen option." + ] + }, + { + "type": "paragraph", + "text": "One payment option per button" + }, + { + "type": "paragraph", + "text": "One payment option per list row, followed by a button that updates to display the chosen option" + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "In-App Purchase" + }, + { + "type": "paragraph", + "text": "Offering Subscriptions" + }, + { + "type": "paragraph", + "text": "App Review Guidelines" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "In-App Purchase — StoreKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Updated artwork and guidance for redeeming offer codes." + ], + [ + "November 3, 2022", + "Added a guideline for displaying the total billing price for every in-app purchase item and consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/in-app-purchase#Best-practices" + }, + { + "title": "Auto-renewable subscriptions", + "url": "/design/human-interface-guidelines/in-app-purchase#Auto-renewable-subscriptions" + }, + { + "title": "Supporting Family Sharing", + "url": "/design/human-interface-guidelines/in-app-purchase#Supporting-Family-Sharing" + }, + { + "title": "Providing help with in-app purchases", + "url": "/design/human-interface-guidelines/in-app-purchase#Providing-help-with-in-app-purchases" + }, + { + "title": "Helping people manage their subscriptions", + "url": "/design/human-interface-guidelines/in-app-purchase#Helping-people-manage-their-subscriptions" + }, + { + "title": "Making signup effortless", + "url": "/design/human-interface-guidelines/in-app-purchase#Making-signup-effortless" + }, + { + "title": "Onboarding", + "url": "/design/human-interface-guidelines/onboarding" + }, + { + "title": "Supporting offer codes", + "url": "/design/human-interface-guidelines/in-app-purchase#Supporting-offer-codes" + }, + { + "title": "offer codes", + "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase#Supporting-offer-codes" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/in-app-purchase#Platform-considerations" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/in-app-purchase#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/in-app-purchase#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/in-app-purchase#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/in-app-purchase#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/in-app-purchase#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/in-app-purchase#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Live Photos", + "url": "https://developer.apple.com/design/human-interface-guidelines/live-photos", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When Live Photos is available, the Camera app captures additional content — including audio and extra frames — before and after people take a photo. People press a Live Photo to see it spring to life." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apply adjustments to all frames. If your app lets people apply effects or adjustments to a Live Photo, make sure those changes are applied to the entire photo. If you don’t support this, give people the option of converting it to a still photo." + }, + { + "type": "paragraph", + "text": "Keep Live Photo content intact. It’s important for people to experience Live Photos in a consistent way that uses the same visual treatment and interaction model across all apps. Don’t disassemble a Live Photo and present its frames or audio separately." + }, + { + "type": "paragraph", + "text": "Implement a great photo sharing experience. If your app supports photo sharing, let people preview the entire contents of Live Photos before deciding to share. Always offer the option to share Live Photos as traditional photos." + }, + { + "type": "paragraph", + "text": "Clearly indicate when a Live Photo is downloading and when the photo is playable. Show a progress indicator during the download process and provide some indication when the download is complete." + }, + { + "type": "paragraph", + "text": "Display Live Photos as traditional photos in environments that don’t support Live Photos. Don’t attempt to replicate the Live Photos experience provided in a supported environment. Instead, show a traditional, still representation of the photo." + }, + { + "type": "paragraph", + "text": "Make Live Photos easily distinguishable from still photos. The best way to identify a Live Photo is through a hint of movement. Because there are no built-in Live Photo motion effects, like the one that appears as you swipe through photos in the full-screen browser of Photos app, you need to design and implement custom motion effects." + }, + { + "type": "paragraph", + "text": "In cases where movement isn’t possible, show a system-provided badge above the photo, either with or without text. Never include a playback button that a viewer can interpret as a video playback button." + }, + { + "type": "paragraph", + "text": "Keep badge placement consistent. If you show a badge, put it in the same location on every photo. Typically, a badge looks best in a corner of a photo." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "In visionOS, people can view a Live Photo, but they can’t capture one." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "PHLivePhoto — PhotoKit" + }, + { + "type": "paragraph", + "text": "LivePhotosKit JS — LivePhotosKit JS" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/live-photos#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/live-photos#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/live-photos#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/live-photos#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/live-photos#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/live-photos#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Mac Catalyst", + "url": "https://developer.apple.com/design/human-interface-guidelines/mac-catalyst", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Before you start", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Many iPad apps are great candidates for creating a Mac app built with Mac Catalyst. This is especially true for apps that already work well on iPad and support key iPad features, such as:" + }, + { + "type": "paragraph", + "text": "Drag and drop. When you support drag and drop in your iPad app, you also get support for drag and drop in the Mac version." + }, + { + "type": "paragraph", + "text": "Keyboard navigation and shortcuts. Even though a physical keyboard may not always be available on iPad, iPad users appreciate using the keyboard to navigate and keyboard shortcuts to streamline their interactions. On the Mac, people expect apps to offer both keyboard navigation and shortcuts." + }, + { + "type": "paragraph", + "text": "Multitasking. Apps that do a good job scaling the interface to support Split View, Slide Over, and Picture in Picture lay the necessary groundwork to support the extensive window resizability that Mac users expect." + }, + { + "type": "paragraph", + "text": "Multiple windows. By supporting multiple scenes on iPad, you also get support for multiple windows in the macOS version of your app." + }, + { + "type": "paragraph", + "text": "Although great iPad apps can provide a solid foundation for creating a Mac app built with Mac Catalyst, some apps rely on frameworks or features that don’t exist on a Mac. For example, if the essential features of your experience require capabilities like gyroscope, accelerometer, or rear camera, frameworks like HealthKit or ARKit, or if the primary function you offer is something like marking, handwriting, or navigation, your app might not be suitable for the Mac." + }, + { + "type": "paragraph", + "text": "Creating a Mac version of your iPad app with Mac Catalyst gives the app automatic support for fundamental macOS features such as:" + }, + { + "type": "list", + "items": [ + "Pointer interactions and keyboard-based focus and navigation", + "Window management", + "Toolbars", + "Rich text interaction, including copy and paste as well as contextual menus for editing", + "File management", + "Menu bar menus", + "App-specific settings in the system-provided Settings app" + ] + }, + { + "type": "paragraph", + "text": "System-provided UI elements take on a more Mac-like appearance, too; for example:" + }, + { + "type": "list", + "items": [ + "Split view", + "File browser", + "Activity view", + "Form sheet", + "Contextual actions", + "Color picker" + ] + }, + { + "type": "paragraph", + "text": "To learn more about the characteristics that distinguish the Mac experience, see Designing for macOS. For developer guidance, see Mac Catalyst." + }, + { + "type": "note", + "text": "Developer noteTo discover how views and controls can change when you create a Mac app using Mac Catalyst, download UIKit Catalog: Creating and customizing views and controls and build the macOS target." + } + ] + }, + { + "heading": "Choose an idiom", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you first create your Mac app using Mac Catalyst, Xcode defaults to the “Scale Interface to Match iPad” setting, or iPad idiom. With this setting, the system ensures that your Mac app appears consistent with the macOS display environment without requiring significant changes to the app’s layout. However, text and graphics may appear slightly less detailed because iPadOS views and text scale down to 77% in macOS when you use the iPad idiom. For example, the system scales text that uses the iPadOS baseline font size of 17pt down to 13pt in macOS." + }, + { + "type": "paragraph", + "text": "When your app feels at home on the Mac using the iPad idiom, consider switching to the Mac idiom. With this setting, text and artwork render in more detail, some interface elements and views take on an even more Mac-like appearance, and graphics-intensive apps may see improved performance and lower power consumption." + }, + { + "type": "paragraph", + "text": "You’re most likely to benefit from the Mac idiom if your app displays a lot of text, detailed artwork, or animations, but choosing this idiom can also mean that you need to spend additional time updating your Mac app’s layout, text, and images." + }, + { + "type": "paragraph", + "text": "When you adopt the Mac idiom, thoroughly audit your app’s layout, and plan to make changes to it. To help with this effort, consider using a separate asset catalog to contain your Mac app’s assets instead of reusing the asset catalog that contains your iPad app’s assets." + }, + { + "type": "paragraph", + "text": "Adjust font sizes as needed. With the Mac idiom, text renders at 100% of its configured size, which can appear too large without adjustment. When possible, use text styles and avoid fixed font sizes." + }, + { + "type": "paragraph", + "text": "Make sure views and images look good in the Mac version of your app. With the Mac idiom, iPadOS views render at 100% of their size, making them appear more detailed. To help you visualize the difference, consider the two depictions of an image asset shown below. One version illustrates how the asset appears when you use the iPad idiom, and the other version shows how the asset appears when you adopt the Mac idiom. Both depictions are zoomed in to show how the image renders with more details when you use the Mac idiom." + }, + { + "type": "note", + "text": "Developer noteWhen you adopt the Mac idiom, the unscaled views and interface elements report different metrics, often resulting in a significant amount of additional work. To reduce the amount of work, avoid using fixed font, view, or layout sizes. For developer guidance, see Choosing a user interface idiom for your Mac app." + }, + { + "type": "paragraph", + "text": "Limit your appearance customizations to standard macOS appearance customizations that are the same or similar to those available in iPadOS. Not all appearance customizations available to iPadOS controls are available to macOS controls." + } + ] + }, + { + "heading": "Integrate the Mac experience", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you use Mac Catalyst to create a Mac version of your iPad app, you need to ensure that your Mac app gives people a rich Mac experience. Regardless of the idiom you choose, it’s essential to go beyond simply displaying your iPadOS layout in a macOS window." + }, + { + "type": "paragraph", + "text": "iPadOS and macOS each define patterns and conventions that are rooted in the different ways people use their devices. Before you dive in and update specific views and controls, become familiar with the main differences between the platforms so you can create a great Mac app." + } + ] + }, + { + "heading": "Navigation", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Many iPad and Mac apps organize data in similar ways, but they use different controls and visual indicators to help people understand and navigate through the data." + }, + { + "type": "paragraph", + "text": "Typically, iPad apps use the following components to organize their content and features:" + }, + { + "type": "list", + "items": [ + "Split views. A split view supports hierarchical navigation, which consists of a two- or three-column interface that shows a primary column, an optional supplementary column, and a secondary pane of content. Frequently, apps use the primary column to create a sidebar-based interface where changes in the sidebar drive changes in the optional supplementary column, which then affect the content in the content pane.", + "Tab bars. A tab bar supports flat navigation by displaying top-level categories in a persistent bar at the bottom of the screen.", + "Page controls. A page control displays dots at the bottom of the screen that indicate the position of the current page in a flat list of pages." + ] + }, + { + "type": "paragraph", + "text": "If you use a tab bar in your iPad app, consider using a split view with a sidebar or a segmented control. Both items are similar to macOS navigation conventions. To choose between a split view or a segmented control, consider the following:" + }, + { + "type": "list", + "items": [ + "A split view with a sidebar displays a list of top-level items, each of which can disclose a list of child items. Using a sidebar streamlines navigation, because each tab’s contents are available within the sidebar. By using a sidebar on both iPad and Mac, you create a consistent layout that makes it easy for iPad users to start using the Mac version of your app.", + "A segmented control and a tab bar both accommodate similar interactions, such as mutually exclusive selection. In general, using a split view instead of a tab bar works better than using a segmented control. However, a segmented control can work well on the Mac if your app uses a flat navigation hierarchy." + ] + }, + { + "type": "paragraph", + "text": "Make sure people retain access to important tab-bar items in the Mac version of your app. Regardless of whether you use a split view or a segmented control instead of a tab bar in your iPad app, be sure to give people quick access to top-level items by listing them in the macOS View menu." + }, + { + "type": "paragraph", + "text": "Offer multiple ways to move between pages. Mac users — especially those who interact using a pointing device or only the keyboard — appreciate Next and Previous buttons in addition to iPad or trackpad gestures that let them swipe between pages." + } + ] + }, + { + "heading": "Inputs", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Although both iPad and Mac accept user input from a range of devices — such as keyboard, mouse, and trackpad — touch interactions are the basis for iPadOS conventions. In contrast, keyboard and mouse interactions inform most macOS conventions." + }, + { + "type": "paragraph", + "text": "Most iPadOS gestures convert automatically when you create your Mac app using Mac Catalyst; for example:" + }, + { + "type": "table", + "rows": [ + [ + "iPadOS gesture…", + "Translates to mouse interaction" + ], + [ + "Tap", + "Left or right click" + ], + [ + "Touch and hold", + "Click and hold" + ], + [ + "Pan", + "Left click and drag" + ] + ] + }, + { + "type": "table", + "rows": [ + [ + "iPadOS gesture…", + "Translates to trackpad gesture" + ], + [ + "Tap", + "Click" + ], + [ + "Touch and hold", + "Click and hold" + ], + [ + "Pan", + "Click and drag" + ], + [ + "Pinch", + "Pinch" + ], + [ + "Rotate", + "Rotate" + ] + ] + }, + { + "type": "note", + "text": "Developer noteThe system sends the two touches in the pinch and rotate gestures to the view under the pointer, not the view under each touch." + } + ] + }, + { + "heading": "App icons", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Create a macOS version of your app icon. Great macOS app icons showcase the lifelike rendering style that people expect in macOS while maintaining a harmonious experience across all platforms." + } + ] + }, + { + "heading": "Layout", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "To take advantage of the wider Mac screen in ways that give Mac users a great experience, consider updating your layout in the following ways:" + }, + { + "type": "list", + "items": [ + "Divide a single column of content and actions into multiple columns.", + "Use the regular-width and regular-height size classes, and consider reflowing elements in the content area to a side-by-side arrangement as people resize the window.", + "Present an inspector UI next to the main content instead of using a popover." + ] + }, + { + "type": "paragraph", + "text": "Consider moving controls from the main UI of your iPad app to your Mac app’s toolbar. Be sure to list the commands associated with these controls in the menus of your Mac app’s menu bar." + }, + { + "type": "paragraph", + "text": "As much as possible, adopt a top-down flow. Mac apps place the most important actions and content near the top of the window. If your iPad app provides controls in a toolbar, put these controls in the window toolbar of the macOS version of your app." + }, + { + "type": "paragraph", + "text": "Relocate buttons from the side and bottom edges of the screen. On iPad, placing buttons on these screen edges can help people reach them, but on a Mac, this ergonomic consideration doesn’t apply. You may want to relocate these controls to other areas or put them in the toolbar of your macOS window." + } + ] + }, + { + "heading": "Menus", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Mac users are familiar with the persistent menu bar and expect to find all of an app’s commands in it. In contrast, iPadOS doesn’t have a persistent menu bar, and iPad users expect to find app commands within the app’s UI or in the shortcut interface that displays when they hold the Command key on a connected keyboard." + }, + { + "type": "note", + "text": "Developer noteTo support keyboard shortcuts for menu commands, use UIKeyCommand. For developer guidance, see Adding menus and shortcuts to the menu bar and user interface." + }, + { + "type": "paragraph", + "text": "If you provide pop-up buttons or pull-down buttons that reveal a menu in your iPad app, the menu automatically takes on a macOS appearance in the Mac app you create with Mac Catalyst." + }, + { + "type": "note", + "text": "Developer noteTo add and remove custom app menus, use UIMenuBuilder and add menu items that represent your iPad app’s commands as menu items with UICommand." + }, + { + "type": "paragraph", + "text": "The system automatically converts the context menus in your iPad app to context menus in the macOS version of your app. As you create the Mac version of your app, consider looking for additional places to support context menus. Mac users tend to expect every object in your app to offer a context menu of relevant actions. Note that on a Mac, a context menu is sometimes called a contextual menu." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iPadOS or macOS. Not supported in iOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Designing for macOS" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Mac Catalyst — UIKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Before you start", + "url": "/design/human-interface-guidelines/mac-catalyst#Before-you-start" + }, + { + "title": "Designing for macOS", + "url": "/design/human-interface-guidelines/designing-for-macos" + }, + { + "title": "Choose an idiom", + "url": "/design/human-interface-guidelines/mac-catalyst#Choose-an-idiom" + }, + { + "title": "Integrate the Mac experience", + "url": "/design/human-interface-guidelines/mac-catalyst#Integrate-the-Mac-experience" + }, + { + "title": "Navigation", + "url": "/design/human-interface-guidelines/mac-catalyst#Navigation" + }, + { + "title": "Split views", + "url": "/design/human-interface-guidelines/split-views" + }, + { + "title": "Tab bars", + "url": "/design/human-interface-guidelines/tab-bars" + }, + { + "title": "Page controls", + "url": "/design/human-interface-guidelines/page-controls" + }, + { + "title": "Inputs", + "url": "/design/human-interface-guidelines/mac-catalyst#Inputs" + }, + { + "title": "App icons", + "url": "/design/human-interface-guidelines/mac-catalyst#App-icons" + }, + { + "title": "Layout", + "url": "/design/human-interface-guidelines/mac-catalyst#Layout" + }, + { + "title": "Menus", + "url": "/design/human-interface-guidelines/mac-catalyst#Menus" + }, + { + "title": "pop-up buttons", + "url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons" + }, + { + "title": "pull-down buttons", + "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/mac-catalyst#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/mac-catalyst#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/mac-catalyst#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/mac-catalyst#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/mac-catalyst#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/mac-catalyst#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Machine learning", + "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In addition to providing familiar features like image recognition and content recommendations, your app can use machine learning to forge deep connections with people and help them accomplish more with less effort." + }, + { + "type": "paragraph", + "text": "For related guidance on how to use machine learning models to enable intelligent content creation experiences, see Generative AI." + } + ] + }, + { + "heading": "Planning your design", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Machine learning apps use models to perform tasks like recognizing images or finding relationships among numerical data. A great machine learning app depends on well-designed models as much as it depends on a well-designed UI and user experience. For insight into the process of designing models, see Create ML." + }, + { + "type": "paragraph", + "text": "As you design your models, keep the intended experience of your app in mind. It can take a long time to adjust the behavior of models, so be prepared to change the way you use data and metrics if the app experience needs to change." + }, + { + "type": "paragraph", + "text": "Designing the UI and user experience of a machine learning app can be uniquely challenging. Because a machine learning app bases its behavior on the data it receives — reacting to changing information and conditions — you can’t design specific reactions to a static set of scenarios. Instead, you design the experience by teaching the app how to interpret data and react accordingly." + }, + { + "type": "paragraph", + "text": "To help you meet this challenge, first consider the role that machine learning plays in your app. Defining the role of machine learning in your app can help you discover areas in which you can explore the ways machine learning can affect the experience your app provides." + }, + { + "type": "paragraph", + "text": "Use the machine learning role you identify to help you define ways your app can receive and display data. There are several patterns — grouped into inputs and outputs — that provide guidance in areas such as getting feedback, displaying data, handling mistakes, and supporting corrections. Use the guidance in these patterns to help you integrate machine learning into your app in ways that people appreciate." + } + ] + }, + { + "heading": "The role of machine learning in your app", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Machine learning systems vary widely, and the ways an app can use machine learning vary widely, too. As you approach the design of your app, think about how its features use machine learning in each of the following areas." + } + ] + }, + { + "heading": "Critical or complementary", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If an app can still work without the feature that machine learning supports, machine learning is complementary to the app; otherwise, it’s a critical dependency. For example:" + }, + { + "type": "list", + "items": [ + "The keyboard uses machine learning to provide QuickType suggestions. Because the keyboard still works without these suggestions, machine learning plays a complementary role in the app.", + "Face ID relies on machine learning to perform accurate face recognition. Without machine learning, Face ID would not work." + ] + }, + { + "type": "paragraph", + "text": "In general, the more critical an app feature is, the more people need accurate and reliable results. On the other hand, if a complementary feature delivers results that aren’t always of the highest quality, people might be more forgiving." + } + ] + }, + { + "heading": "Private or public", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Machine learning results depend on data. To make good design decisions, you need to know as much as possible about the types of data your app feature needs. In general, the more sensitive the data, the more serious the consequences of inaccurate or unreliable results. For example:" + }, + { + "type": "list", + "items": [ + "If a health app misinterprets data and incorrectly recommends a visit to the doctor, people are likely to experience anxiety and may lose trust in the app.", + "If a music app misinterprets data and recommends an artist that people don’t like, they’re likely to view the result as an inconsequential mistake." + ] + }, + { + "type": "paragraph", + "text": "As with critical app features, features that use sensitive data must prioritize accuracy and reliability. Regardless of the sensitivity of the data, all apps must protect user privacy at all times." + } + ] + }, + { + "heading": "Proactive or reactive", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A proactive app feature provides results without people requesting it to do so. Proactive features can prompt new tasks and interactions by providing unexpected, sometimes serendipitous results. In contrast, a reactive app feature provides results when people ask for them or when they take certain actions. Reactive features typically help people as they perform their current task. For example:" + }, + { + "type": "list", + "items": [ + "QuickType suggests words in reaction to what people type.", + "Siri Suggestions can proactively suggest a shortcut based on people’s recent routines." + ] + }, + { + "type": "paragraph", + "text": "Because people don’t ask for the results that a proactive feature provides, they may have less tolerance for low-quality information. To reduce the possibility that people will find proactive results intrusive or irrelevant, you may need to use additional data for the feature." + } + ] + }, + { + "heading": "Visible or invisible", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Apps may use machine learning to support visible or invisible features. People are usually aware of visible app features because such features tend to offer suggestions or choices that people view and interact with. For example, a visible keyboard feature tries to guess the word that people are typing and presents the most likely words in a list from which people choose." + }, + { + "type": "paragraph", + "text": "As the name suggests, an invisible feature provides results that aren’t obvious to people. For example, the keyboard learns how people type over time so it can optimize the tap area for each key and help them make fewer typing mistakes. Because this app feature improves the typing experience without requiring people to make choices, many people aren’t aware that the feature exists." + }, + { + "type": "paragraph", + "text": "People’s impression of the reliability of results can differ depending on whether a feature is visible or invisible. With a visible feature, people form an opinion about the feature’s reliability as they choose from its results. It’s harder for an invisible feature to communicate its reliability — and potentially receive feedback — because people may not be aware of the feature at all." + } + ] + }, + { + "heading": "Dynamic or static", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "All machine learning models can improve, but some improve dynamically, as people interact with the app feature, and others improve offline and affect the feature only when the app updates. For example:" + }, + { + "type": "list", + "items": [ + "Face ID improves dynamically as people’s faces gradually change over time.", + "Photos improves its object recognition capabilities with every new iOS release." + ] + }, + { + "type": "paragraph", + "text": "In addition to the frequency of app updates, static or dynamic improvements can affect other parts of the user experience, too. For example, dynamic features often incorporate forms of calibration and feedback (either implicit or explicit), whereas static features might not." + } + ] + }, + { + "heading": "Explicit feedback", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Explicit feedback provides actionable information your app can use to improve the content and experience it presents to people. Unlike implicit feedback — which is information an app gleans from user actions — explicit feedback is information people provide in response to a specific request from the app." + }, + { + "type": "paragraph", + "text": "Favoriting — marking an item for quick access in the future — and social feedback — expressing emotions towards others — are common user interactions that seem like mechanisms that supply explicit feedback. However, these tools actually provide implicit feedback because they don’t support app-specific requests. People use favoriting and social feedback to accomplish their own goals and apps can gather implicit feedback from these interactions." + }, + { + "type": "paragraph", + "text": "Request explicit feedback only when necessary. People must take action to provide explicit feedback, so it’s best to avoid requesting it if possible. Instead, consider using implicit feedback to learn how people interact with your app without asking them to do extra work." + }, + { + "type": "paragraph", + "text": "Always make providing explicit feedback a voluntary task. You want to communicate that explicit feedback can help improve the experience without making people feel that providing it is mandatory." + }, + { + "type": "paragraph", + "text": "Use simple, direct language to describe each explicit feedback option and its consequences. Avoid using imprecise terms such as dislike because such terms don’t convey consequences and can be hard to translate. Instead, describe each option in a way that helps people understand what happens when they choose the option, such as:" + }, + { + "type": "list", + "items": [ + "Suggest less pop music", + "Suggest more thrillers", + "Mute politics for a week" + ] + }, + { + "type": "paragraph", + "text": "Add icons to an option description if it helps people understand it. Icons can help clarify or emphasize part of an option description. Avoid using an icon by itself, because it might not be clear enough to communicate granularity or consequences." + }, + { + "type": "paragraph", + "text": "Consider offering multiple options when requesting explicit feedback. Providing multiple options can give people a sense of control and help them identify unwanted suggestions and remove them from your app. To help people provide feedback, consider offering options that become progressively more specific so that it’s easy for people to clarify their response." + }, + { + "type": "paragraph", + "text": "Act immediately when you receive explicit feedback and persist the resulting changes. For example, if people identify content they don’t want to see, that the content instantly disappears from their view and doesn’t appear elsewhere in your app. When you react immediately to feedback and show that your app remembers it, you build people’s trust in the value of providing it." + }, + { + "type": "paragraph", + "text": "Consider using explicit feedback to help improve when and where you show results. For example, people might like a result, but they may not want to see it at certain times or in certain contexts. Explicit feedback on when and where to show results can help you fine-tune the experience people have in your app." + } + ] + }, + { + "heading": "Implicit feedback", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Implicit feedback is information that arises as people interact with your app’s features. Unlike the specific responses you get from explicit feedback, implicit feedback gives you a wide range of information about user behavior and preferences. Although incorporating implicit feedback isn’t required for a great machine learning app, the feedback can help you improve your app’s user experience without asking people to do any extra work." + }, + { + "type": "paragraph", + "text": "Always secure people’s information. Implicit feedback can gather potentially sensitive user information, so you must be particularly careful to maintain strict controls on user privacy." + }, + { + "type": "paragraph", + "text": "Help people control their information. As an app developer, you know that the more you understand about the behavior of your users — both within your app and in other apps — the more you can improve the experience your app provides. Although most people understand the benefits of making their information available to multiple apps, they may still be surprised when things they do in one app affect experiences they have in a different app. Worse, people may assume that apps are sharing their private information, which can cause them to lose trust in the apps. It’s important to tell people how your app gets and shares their information and to give people ways to restrict the flow of their information." + }, + { + "type": "paragraph", + "text": "Don’t let implicit feedback decrease people’s opportunities to explore. Implicit feedback tends to reinforce people’s behavior, which can improve the user experience in the short term, but may worsen it in the long term. For example, it might seem like a good idea to give people a set of suggestions that matches all the things they’re interested in now, but doing so doesn’t encourage them to explore new things." + }, + { + "type": "paragraph", + "text": "When possible, use multiple feedback signals to improve suggestions and mitigate mistakes. Implicit feedback is indirect, so it can be difficult to discern a person’s actual intent in the information you gather. For example, if someone views a photo, shares it in a message, and adds it to a shared album, it doesn’t necessarily mean they have positive feelings about the photo. Incorporate implicit feedback from multiple sources and interactions to help you avoid misinterpreting people’s intentions." + }, + { + "type": "paragraph", + "text": "Consider withholding private or sensitive suggestions. People often share their accounts and devices with others, or switch from using a personal device to a communal one. If your app receives implicit feedback related to private or sensitive topics, avoid offering recommendations based on that feedback." + }, + { + "type": "paragraph", + "text": "Prioritize recent feedback. People’s tastes can change frequently, so base your recommendations on recent implicit feedback. For example, Face ID prioritizes recent facial input because it’s most likely to represent what the person looks like now. If recent feedback isn’t available, you can fall back to historical feedback." + }, + { + "type": "paragraph", + "text": "Use feedback to update predictions on a cadence that matches the person’s mental model of the feature. For example, people expect typing suggestions to update immediately as they’re typing. On the other hand, giving people continuously updated song recommendations makes it hard to consider individual songs and could make them feel rushed or overwhelmed." + }, + { + "type": "paragraph", + "text": "Be prepared for changes in implicit feedback when you make changes to your app’s UI. Even small UI changes can lead to noticeable changes in the amount and types of implicit feedback. For example, changing the location of a button can affect how people use it, even if there’s no change in the benefit they get from the button’s action. Take such changes into account when interpreting the implicit feedback you receive from interactions in your app." + }, + { + "type": "paragraph", + "text": "Beware of confirmation bias. Implicit feedback is constrained by what people can actually see and do in your app and other apps — it rarely gives you insight into new things they might like to do. Avoid relying solely on implicit feedback to inform your results." + } + ] + }, + { + "heading": "Calibration", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Calibration is a process during which people provide information that an app feature needs before it can function. To use Face ID, for example, a person must first scan their face." + }, + { + "type": "paragraph", + "text": "In general, only use calibration when your feature can’t function without that initial information. If your feature can work without calibration, consider using other ways to gather the information you need, such as implicit feedback or possibly explicit feedback." + }, + { + "type": "paragraph", + "text": "Always secure people’s information. During calibration, people may provide sensitive information and you must make sure it remains secure." + }, + { + "type": "paragraph", + "text": "Be clear about why you need people’s information. Typically, calibration is required before people can use a feature, so it’s essential that they understand the value of providing their information. As you briefly describe how people can benefit from your feature, emphasize what it does rather than how it works." + }, + { + "type": "paragraph", + "text": "Collect only the most essential information. Designing a unique experience that requests a minimal amount of information can make people more comfortable participating in the process and increase their trust in your app." + }, + { + "type": "paragraph", + "text": "Avoid asking people to participate in calibration more than once. Also, it’s best when calibration occurs early in the user experience. As people continue using your app or feature, you can use implicit or explicit feedback to evolve your information about them without asking them to participate again. An exception is a feature that needs calibration with an object instead of a person. For example, an app that helps people improve their baseball swing might need to calibrate with each new baseball field." + }, + { + "type": "paragraph", + "text": "Make calibration quick and easy. Even a brief calibration experience takes time and requires effort from people. An ideal calibration experience makes it easy for people to respond, without compromising the quality of the information they provide. The following guidelines can help you create a streamlined calibration experience." + }, + { + "type": "list", + "items": [ + "Prioritize getting a few pieces of important information and infer the rest from other sources or by getting people’s feedback.", + "Avoid asking for information that most people would have to look up.", + "Avoid asking people to perform actions that might be difficult." + ] + }, + { + "type": "paragraph", + "text": "Make sure people know how to perform calibration successfully. After people decide to participate in calibration, give them an explicit goal and show their progress towards it. For example, Face ID calibration briefly describes what people need to do and changes the appearance of the tick marks encircling the face as people progress through scanning." + }, + { + "type": "paragraph", + "text": "Immediately provide assistance if progress stalls. When progress stalls, people can feel stuck or powerless, and they may lose trust in your app. In this situation, it’s crucial to give people actionable recommendations that quickly get them back on track. As you provide this guidance, never imply that something’s wrong or that people are at fault, and never leave people without a clear next step." + }, + { + "type": "paragraph", + "text": "Confirm success. The moment people successfully complete calibration, reward their time and effort by giving them a clear path towards using the feature. Providing an explicit completion to the calibration experience reinforces the unique nature of the experience and helps people switch their focus to your feature." + }, + { + "type": "paragraph", + "text": "Let people cancel calibration at any time. Make sure you give people an easy way to cancel the experience at any point and avoid implying any judgement about their choice. There’s no need to provide any messaging that mentions the canceled calibration, because the next time people attempt to use the feature, they’ll have another chance to participate." + }, + { + "type": "paragraph", + "text": "Give people a way to update or remove information they provided during calibration. Letting people edit their information gives them more control and can lead them to have greater trust in your app. Although the calibration experience can help people edit their responses, it’s a good idea to let people edit their information outside of the calibration experience so that they feel free to make changes at any time." + } + ] + }, + { + "heading": "Corrections", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People use corrections to fix mistakes that apps make. For example, if a photo app automatically crops a photo in a way people don’t like, they can correct the mistake by cropping the photo in a different way." + }, + { + "type": "paragraph", + "text": "Give people familiar, easy ways to make corrections. When your app makes a mistake, you don’t want people to be confused about how to correct it. You can avoid causing confusion by showing the steps your app takes as it performs the automated task. For example, Photos highlights the controls it uses to auto-crop a photograph so that people can use the same controls to refine or undo the results." + }, + { + "type": "paragraph", + "text": "Provide immediate value when people make a correction. Reward people’s effort by instantly displaying corrected content, especially when the feature is critical or you’re responding to direct user input. Also, be sure to persist the updates so people don’t have to make the same corrections again." + }, + { + "type": "paragraph", + "text": "Let people correct their corrections. Sometimes, people make a correction without realizing that they’ve made a mistake. As you do with all corrections, respond immediately to an updated correction and persist the update." + }, + { + "type": "paragraph", + "text": "Always balance the benefits of a feature with the effort required to make a correction. People may not mind when a feature that automates a task makes a mistake, but they’re likely to stop using the feature if it seems easier to perform the task themselves." + }, + { + "type": "paragraph", + "text": "Never rely on corrections to make up for low-quality results. Although corrections can reduce the impact of a mistake, depending on them may erode people’s trust in your app and reduce the value of your feature." + }, + { + "type": "paragraph", + "text": "Learn from corrections when it makes sense. A correction is a type of implicit feedback that can give you valuable information about ways your app doesn’t meet people’s expectations. Before you use a correction to update your models, make sure that the correction will lead to higher quality results." + }, + { + "type": "paragraph", + "text": "When possible, use guided corrections instead of freeform corrections. Guided corrections suggest specific alternatives, so they require less user effort; freeform corrections don’t suggest specific alternatives, so they require more input from people. An example of guided correction is a speech-to-text feature that gives people a list of alternative text completions from which to choose. In contrast, Photos offers freeform correction so that people can adjust the auto-cropping of a photo as they see fit. If it makes sense in your app, you can support a combination of guided and freeform corrections." + } + ] + }, + { + "heading": "Mistakes", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "It’s inevitable that your app will make mistakes. Although people may not expect perfection, mistakes can damage their experience and decrease their trust in your app. To help you avoid negative consequences, it’s crucial to:" + }, + { + "type": "list", + "items": [ + "Anticipate mistakes. As much as possible, design ways to avoid mistakes and mitigate them when they happen.", + "Help people handle mistakes. Mistakes can have a wide range of consequences, so the tools you provide to handle a mistake must be able to address those consequences.", + "Learn from mistakes when doing so improves your app. In some cases, learning from a mistake might have undesirable effects, such as causing unpredictability in the user experience. When it makes sense, use each mistake as a data point that can refine your machine learning models and improve your app." + ] + }, + { + "type": "paragraph", + "text": "There are several machine learning patterns that can help you address mistakes:" + }, + { + "type": "list", + "items": [ + "Limitations help you set people’s expectations about the accuracy of your suggestions.", + "Corrections give people a way to be successful even when your results are wrong.", + "Attribution gives people insight into where suggestions come from, which can help them understand mistakes.", + "Confidence helps you gauge the quality of your results, which can impact how you present them.", + "Feedback — both explicit and implicit — lets people tell you about mistakes that you might not be aware of." + ] + }, + { + "type": "paragraph", + "text": "Understand the significance of a mistake’s consequences. For example, incorrect keyboard suggestions might annoy people, but suggesting a travel route that results in a missed flight is a serious inconvenience. Show empathy by providing corrective actions or tools that match the seriousness of the mistake." + }, + { + "type": "paragraph", + "text": "Make it easy for people to correct frequent or predictable mistakes. If you don’t give people an easy way to correct mistakes, they can lose trust in your app." + }, + { + "type": "paragraph", + "text": "Continuously update your feature to reflect people’s evolving interests and preferences and help avoid mistakes. For example, you can use implicit feedback to discover changes in people’s tastes and habits. It’s also a good idea to update your feature with domain-specific information, such as current trends in popular entertainment. Ideally, people don’t have to do any work to benefit from improvements in your app." + }, + { + "type": "paragraph", + "text": "When possible, address mistakes without complicating the UI. Some patterns, such as corrections and limitations, tend to integrate seamlessly with an app’s UI, whereas others, like attributions, can be harder to integrate. Balance a pattern’s effect on the UI with its potential for compounding the mistake. For example, if you update the UI with an attribution that turns out to be wrong, the effect of the original mistake is magnified." + }, + { + "type": "paragraph", + "text": "Be especially careful to avoid mistakes in proactive features. A proactive feature — like a suggestion based on people’s behaviors — promises valuable results without asking people to do anything to get them. However, because people don’t request a proactive feature, they often have less patience with its mistakes. Mistakes made by proactive features can also cause people to feel that they have less control." + }, + { + "type": "paragraph", + "text": "As you work on reducing mistakes in one area, always consider the effect your work has on other areas and overall accuracy. For example, optimizing an image-recognition app to improve how it recognizes dogs might result in a decreased ability to recognize cats. As your models evolve, be prepared for mistakes to evolve, too. Use what you know about people’s preferences to help you determine the areas to work on." + } + ] + }, + { + "heading": "Multiple options", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Depending on the design of your feature, it might work best to present a single result or multiple results from which people can choose. Providing multiple options can give people a greater sense of control and can help bridge the gap between your model’s predictions and what people actually want. Multiple options can also encourage people to have realistic expectations about the types of results your app generates." + }, + { + "type": "paragraph", + "text": "You might present multiple options to people in the following contexts:" + }, + { + "type": "list", + "items": [ + "Suggested options, a proactive feature that suggests content to people based on the their past interactions. For example, For You recommendations from Apple Music.", + "Requested options, a reactive feature that suggests potential next steps to people based on their recent actions. For example, Quick Type suggestions.", + "Corrections, which are actions people take to fix mistakes your app has made when it’s acting on their behalf. For example, the Photos Auto-Crop feature." + ] + }, + { + "type": "paragraph", + "text": "Prefer diverse options. When possible, balance the accuracy of a response with the diversity of multiple options. For example, Apple Maps generally suggests more than one route to a destination, such as a route without tolls, a scenic route, or a route that uses highways. Providing different types of options helps people choose the one that they prefer and can also suggest new items that might interest them." + }, + { + "type": "paragraph", + "text": "In general, avoid providing too many options. People must evaluate each option before making a choice, so more options increases cognitive load. When possible, list options on one screen so people don’t have to scroll to find the right one." + }, + { + "type": "paragraph", + "text": "List the most likely option first. When you know how your confidence values correlate with the quality of your results, you might use them to rank the options. You might also consider using contextual information, such as the time of day or the current location, to help you determine the most likely option. If it makes sense in your app, select the first option by default so people can quickly achieve their goals without reading through every option." + }, + { + "type": "paragraph", + "text": "Make options easy to distinguish and choose. For example, in a routing app, people often need to make route choices quickly to avoid going the wrong way. When options look similar, help people distinguish between them by providing a brief description of each one and taking particular care to highlight the differences. In cases where there are too many options to display in a single view, such as with content recommendations, consider grouping options in categories that people can scan rapidly." + }, + { + "type": "paragraph", + "text": "Learn from selections when it makes sense. People give you implicit feedback every time they make a selection. When it doesn’t adversely affect the user experience, use this feedback to refine the options you provide and increase the chance that you’ll present the most likely option first. In general, continuing to offer incorrect results is likely to decrease people’s trust in the quality of your app’s predictions." + } + ] + }, + { + "heading": "Confidence", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Confidence indicates the measure of certainty for a result. Not all models produce confidence values by default, so you might consider generating them if you can use them to improve the user experience of your app." + }, + { + "type": "paragraph", + "text": "Although it might seem like higher confidence produces a higher quality result — and therefore a better user experience — it doesn’t necessarily work that way. You need to verify that your confidence values correspond to the quality of your results. For example, you might review values for multiple confidence thresholds or compare values across multiple versions of your app. If you’re not sure how your confidence values correlate with the quality of your results, it’s not a good idea to convey confidence to people." + }, + { + "type": "paragraph", + "text": "Know what your confidence values mean before you decide how to present them. For example, people may forgive low-quality results from critical or complementary features — especially when results are accompanied by attribution or other contextual information — but presenting low-quality results in a prominent way is likely to erode trust in your app." + }, + { + "type": "paragraph", + "text": "In general, translate confidence values into concepts that people already understand. Simply displaying a confidence value doesn’t necessarily help people understand how it relates to a result. For example, a feature that suggests new music based on a person’s listening habits might calculate that there’s a 97% match between a new song and the songs they usually listen to. However, displaying “97% match” next to the new song as an attribution doesn’t communicate enough information to help people make a choice. In contrast, providing an attribution that clearly identifies the behavior — such as “Because you listen to pop music” — can be more actionable." + }, + { + "type": "paragraph", + "text": "In situations where attributions aren’t helpful, consider ranking or ordering the results in a way that implies confidence levels. If you must display confidence directly, consider expressing it in terms of semantic categories. For example, a feature that predicts travel prices might replace ranges of confidence numbers with categories like “high chance” and “low chance” to give context to the values and help people understand and compare the results." + }, + { + "type": "paragraph", + "text": "In scenarios where people expect statistical or numerical information, display confidence values that help them interpret the results. For example, weather predictions, sports statistics, and polling numbers are often accompanied by specific values that express the accuracy of the data as an interval or a percentage." + }, + { + "type": "paragraph", + "text": "Whenever possible, help people make decisions by conveying confidence in terms of actionable suggestions. Understanding people’s goals is key to expressing confidence in ways that help them make decisions. For example, if your feature predicts when an item will be at its lowest price, you know that people want to optimize how they spend their time and money. For a feature like this, displaying percentages or other numerical confidence values would be less valuable than providing actionable suggestions like “This is a good time to buy,” or “Consider waiting for a better price.”" + }, + { + "type": "paragraph", + "text": "Consider changing how you present results based on different confidence thresholds. If high or low levels of confidence have a meaningful impact on the ways people can experience the results, it’s a good idea to adapt your presentation accordingly. For example, when confidence is high, the face recognition feature in Photos simply displays the photos that contain a specific person, but when confidence is lower, the feature asks people to confirm whether the photos contain the person before showing more." + }, + { + "type": "paragraph", + "text": "When you know that confidence values correspond to result quality, you generally want to avoid showing results when confidence is low. Especially when a feature is proactive and can make unbidden suggestions, poor results can cause people to be annoyed and even lose trust in the feature. For suggestions and proactive features, it’s a good idea to set a confidence threshold below which you don’t offer results." + } + ] + }, + { + "heading": "Attribution", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "An attribution expresses the underlying basis or rationale for a result, without explaining exactly how a model works. Depending on the design of your app, you might want to use attributions to impart transparency and give people insight into your results. For example, if your app suggests books for people to read, you might use an attribution like “Because you’ve read mysteries” when you suggest books in the “thrillers” category." + }, + { + "type": "paragraph", + "text": "To help you decide whether to include attributions in your app, consider how you want them to affect people. For example, you might want attributions to:" + }, + { + "type": "list", + "items": [ + "Encourage people to change what they do in your app", + "Minimize the impact of mistakes", + "Help people build a mental model of your feature", + "Promote trust in your app over time" + ] + }, + { + "type": "paragraph", + "text": "Consider using attributions to help people distinguish among results. For example, if you present a set of results as multiple options, including attributions can help people choose an option based on their understanding of the premise that led to it, such as “New books by authors you’ve read.”" + }, + { + "type": "paragraph", + "text": "Avoid being too specific or too general. Overly specific attributions can make people feel like they have to do additional work to interpret the results, whereas overly general attributions typically don’t provide useful information. In apps that make content recommendations, general attributions can make people feel like your app is not treating them as individuals, but overly specific attributions can make people think that your app is watching them too closely. The best attributions strike a balance between these extremes." + }, + { + "type": "paragraph", + "text": "Keep attributions factual and based on objective analysis. To be useful, an attribution needs to help people reason about a result; you don’t want to provoke an emotional response. Don’t provide an attribution that implies understanding or judgment of people’s emotions, preferences, or beliefs. For example, an app that recommends new content to people can use an attribution like “Because you’ve read nonfiction” instead of an attribution like “Because you love nonfiction.”" + }, + { + "type": "paragraph", + "text": "In general, avoid technical or statistical jargon. In most situations, using percentages, statistics, and other technical jargon doesn’t help people assess the results you provide. The exception to this is when the result itself is of a statistical or technical nature, such as information in the areas of weather, sports, polling and election results, or scientific data." + } + ] + }, + { + "heading": "Limitations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Every feature — whether it’s based on machine learning or not — has certain limitations to what it can deliver. In general, there are two types of limitations: things a feature can’t do well and things a feature can’t do at all. When there’s a mismatch between people’s expectations about a feature and what the feature can actually accomplish, a limitation can seem like a defect. For example, people might expect:" + }, + { + "type": "list", + "items": [ + "Photos to perform a search that covers every category they can imagine", + "Siri to respond to queries that aren’t well defined, like “What is the meaning of life?”", + "FaceID to work from every angle" + ] + }, + { + "type": "paragraph", + "text": "An important part of the design process is to identify the scenarios where limitations impact the user experience and design ways to help people work with them. For example:" + }, + { + "type": "list", + "items": [ + "Set people’s expectations before they use the feature.", + "Show people how to get the best results while they’re using the feature.", + "When inferior results occur, explain why so that people can understand the feature better." + ] + }, + { + "type": "paragraph", + "text": "Help people establish realistic expectations. When a limitation may have a serious effect on user experience but happens rarely, consider making people aware of the limitation before they use your app or feature. You might describe the limitation in marketing materials or within the feature’s context so that people can decide how they want to rely on the feature. If the effects of a limitation aren’t serious, you can help set people’s expectations by providing attributions." + }, + { + "type": "paragraph", + "text": "Demonstrate how to get the best results. If you don’t provide guidance for using a feature, people may assume it’ll do everything they want. When you proactively show people how to get good results, you help them benefit from the feature and establish a more accurate mental model of the feature’s capabilities. There are many ways to show people the best ways to use a feature, such as:" + }, + { + "type": "list", + "items": [ + "Use placeholder text to suggest input. In Photos, the search bar displays the text “Photos, People, Places…” to help people understand what they can search for before they begin typing. Photos also displays a description of how it scans the photo library to offer search suggestions.", + "As people interact with the feature, provide feedback on their actions to guide them towards a result without overwhelming them. For example, while people are interacting with Animoji, the feature responds to current conditions and suggests how people can improve their results by adjusting the lighting or moving closer to the camera.", + "Suggest alternative ways to accomplish the goal instead of showing no results. To do this successfully, you need to understand the goal well enough to suggest alternatives that make sense. For example, if people ask Siri to set a timer on a Mac, Siri suggests setting a reminder instead, because timers aren’t available in macOS. This suggestion makes sense because people’s goal is to receive an alert at a certain time." + ] + }, + { + "type": "paragraph", + "text": "Explain how limitations can cause unsatisfactory results. People can get frustrated when it seems that your feature works intermittently. Ideally, your feature can recognize and describe the reasons for poor results to make people aware of the limitations and help them to adjust their expectations. For example, Animoji tells people that it doesn’t work well in the dark." + }, + { + "type": "paragraph", + "text": "Consider telling people when limitations are resolved. When people use a feature frequently, they learn to avoid the interactions that fail because of the feature’s limitations. When you update your app to remove a limitation, you might want to notify people so that they can adjust their mental model of your feature and return to interactions they’d previously avoided." + } + ] + }, + { + "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": "Generative AI" + }, + { + "type": "paragraph", + "text": "Privacy" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Intelligence and machine learning" + }, + { + "type": "paragraph", + "text": "Create ML" + }, + { + "type": "paragraph", + "text": "Core ML" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "October 24, 2023", + "Added art to Corrections section." + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Generative AI", + "url": "/design/human-interface-guidelines/generative-ai" + }, + { + "title": "Planning your design", + "url": "/design/human-interface-guidelines/machine-learning#Planning-your-design" + }, + { + "title": "role", + "url": "/design/human-interface-guidelines/machine-learning#The-role-of-machine-learning-in-your-app" + }, + { + "title": "Critical or complementary", + "url": "/design/human-interface-guidelines/machine-learning#Critical-or-complementary" + }, + { + "title": "Private or public", + "url": "/design/human-interface-guidelines/machine-learning#Private-or-public" + }, + { + "title": "Proactive or reactive", + "url": "/design/human-interface-guidelines/machine-learning#Proactive-or-reactive" + }, + { + "title": "Visible or invisible", + "url": "/design/human-interface-guidelines/machine-learning#Visible-or-invisible" + }, + { + "title": "Dynamic or static", + "url": "/design/human-interface-guidelines/machine-learning#Dynamic-or-static" + }, + { + "title": "calibration", + "url": "/design/human-interface-guidelines/machine-learning#Calibration" + }, + { + "title": "implicit", + "url": "/design/human-interface-guidelines/machine-learning#Implicit-feedback" + }, + { + "title": "explicit", + "url": "/design/human-interface-guidelines/machine-learning#Explicit-feedback" + }, + { + "title": "multiple options", + "url": "/design/human-interface-guidelines/machine-learning#Multiple-options" + }, + { + "title": "Corrections", + "url": "/design/human-interface-guidelines/machine-learning#Corrections" + }, + { + "title": "Mistakes", + "url": "/design/human-interface-guidelines/machine-learning#Mistakes" + }, + { + "title": "Limitations", + "url": "/design/human-interface-guidelines/machine-learning#Limitations" + }, + { + "title": "Attribution", + "url": "/design/human-interface-guidelines/machine-learning#Attribution" + }, + { + "title": "Confidence", + "url": "/design/human-interface-guidelines/machine-learning#Confidence" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/machine-learning#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/machine-learning#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/machine-learning#Related" + }, + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/privacy" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/machine-learning#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/machine-learning#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/machine-learning#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Maps", + "url": "https://developer.apple.com/design/human-interface-guidelines/maps", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A map uses a familiar interface that supports much of the same functionality as the system-provided Maps app, such as zooming, panning, and rotation. A map can also include annotations and overlays and show routing information, and you can configure it to use a standard graphical view, a satellite image-based view, or a view that’s a hybrid of both." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "In general, make your map interactive. People expect to be able to zoom, pan, and otherwise interact with maps in familiar ways. Noninteractive elements that obscure the map can interfere with people’s expectations for how maps behave." + }, + { + "type": "paragraph", + "text": "Pick a map emphasis style that suits the needs of your app. There are two emphasis styles to choose from:" + }, + { + "type": "list", + "items": [ + "The default style presents a version of the map with fully saturated colors, and is a good option for most standard map applications without a lot of custom elements. This style is also useful for keeping visual alignment between your map and the Maps app, in situations when people might switch between them.", + "The muted style, by contrast, presents a desaturated version of the map. This style is great if you have a lot of information-rich content that you want to stand out against the map." + ] + }, + { + "type": "paragraph", + "text": "Default style" + }, + { + "type": "paragraph", + "text": "Muted style" + }, + { + "type": "paragraph", + "text": "For developer guidance, see MKStandardMapConfiguration.EmphasisStyle." + }, + { + "type": "paragraph", + "text": "Help people find places in your map. Consider offering a search feature combined with a way to filter locations by category. The search field for a shopping mall map, for example, might include filters that make it easy to find common store types, like clothing, housewares, electronics, jewelry, and toys." + }, + { + "type": "paragraph", + "text": "Clearly identify elements that people select. When someone selects a specific area or other element on the map, use distinct styling like an outline and color variation to call attention to the selection." + }, + { + "type": "paragraph", + "text": "Cluster overlapping points of interest to improve map legibility. A cluster uses a single pin to represent multiple points of interest within close proximity. As people zoom in on a map, clusters expand to progressively reveal individual points of interest." + }, + { + "type": "paragraph", + "text": "Points of interest in a cluster" + }, + { + "type": "paragraph", + "text": "Individual points of interest when zoomed in" + }, + { + "type": "paragraph", + "text": "Help people see the Apple logo and legal link. It’s fine when parts of your interface temporarily cover the logo and link, but don’t cover these elements all the time. Follow these guidelines to help keep the Apple logo and legal link visible:" + }, + { + "type": "list", + "items": [ + "Use adequate padding to separate the logo and link from the map boundaries and your custom controls. For example, it works well to use 7 points of padding on the sides of the elements and 10 points above and below them.", + "Avoid causing the logo and link to move with your interface. It’s best when the Apple logo and legal link appear to be fixed to the map.", + "If your custom interface can move relative to the map, use the lowest position of the custom element to determine the placement of the logo and link. For example, if your app lets people pull up a custom card from the bottom of the screen, place the Apple logo and legal link 10 points above the lowest resting position of the card." + ] + }, + { + "type": "note", + "text": "NoteThe Apple logo and legal link aren’t shown on maps that are smaller than 200x100 pixels." + } + ] + }, + { + "heading": "Custom information", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use annotations that match the visual style of your app. Annotations identify custom points of interest on your map. The default annotation marker has a red tint and a white pin icon. You can change the tint to match the color scheme of your app. You can also change the icon to a string or image, like a logo. An icon string can contain any characters, including Unicode characters, but keep it to two to three characters in length for readability. For developer guidance, see MKAnnotationView." + }, + { + "type": "paragraph", + "text": "If you want to display custom information that’s related to standard map features, consider making them independently selectable. When you support selectable map features, the system treats Apple-provided features (including points of interest, territories, and physical features) independently from other annotations that you add. You can configure custom appearances and information to represent these features when people select them. For developer guidance, see MKMapFeatureOptions." + }, + { + "type": "paragraph", + "text": "Use overlays to define map areas with a specific relationship to your content." + }, + { + "type": "list", + "items": [ + "Above roads, the default level, places the overlay above roads but below buildings, trees, and other features. This is great for situations where you want people to have an idea of what’s below the overlay, while still clearly understanding that it’s a defined space.", + "Above labels places the overlay above both roads and labels, hiding everything beneath it. This is useful for content that you want to be fully abstracted from the features of the map, or when you want to hide areas of the map that aren’t relevant." + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see Displaying overlays on a map and MKOverlayLevel." + }, + { + "type": "paragraph", + "text": "Make sure there’s enough contrast between custom controls and the map. Insufficient contrast makes controls hard to see and can cause them to blend in with the map. Consider using a thin stroke or light drop shadow to help a custom control stand out, or applying blend modes to the map area to increase its contrast with the controls atop it." + } + ] + }, + { + "heading": "Place cards", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Place cards display rich place information in your app or website, such as operating hours, phone numbers, addresses, and more. This enables you to provide structured and up-to-date information for places that you specify, and add depth to search results." + } + ] + }, + { + "heading": "Displaying place cards in a map", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "You can present a place card that appears directly in your map anytime someone selects a place. This is a great way to provide place information in a map with multiple places that you specify, like a map of bookstores that an author plans to visit on their book signing tour. For developer guidance, see mapItemDetailSelectionAccessory(_:), mapView(_:selectionAccessoryFor:), and selectionAccessory." + }, + { + "type": "paragraph", + "text": "You can also display place cards for other places on a map, such as points of interest, territories, and physical features, to provide valuable context to people about nearby places. For developer guidance, see mapFeatureSelectionAccessory(_:), mapView(_:selectionAccessoryFor:), and selectableMapFeatureSelectionAccessory." + }, + { + "type": "note", + "text": "Developer noteIn websites, you can embed a custom map that displays a place card by default for a single place that you specify. For developer guidance, see Displaying place information using the Maps Embed API." + }, + { + "type": "paragraph", + "text": "The system defines several place card styles, which specify the size, appearance, and information included in a place card." + }, + { + "type": "list", + "items": [ + "The automatic style lets the system determine the place card style based on the size of your map view.", + "The callout style displays a place card in a popover style next to the selected place. You can further specify the style of a callout — the full callout style displays a large, detailed place card, and the compact callout style displays a space-saving, more concise place card. If you don’t specify a callout style, the system defaults to the automatic callout style, which determines the callout style based on your map’s view size.", + "The caption style displays an “Open in Apple Maps” link.", + "The sheet style displays a place card in a sheet." + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see MapItemDetailSelectionAccessoryStyle, MKSelectionAccessory.MapItemDetailPresentationStyle, and PlaceSelectionAccessoryStyle." + }, + { + "type": "paragraph", + "text": "Full callout style place cards appear differently depending on a person’s device. The system presents the full callout style place card in a popover style in iPadOS and macOS, and as a sheet in iOS." + }, + { + "type": "paragraph", + "text": "Consider your map presentation when choosing a style. The full callout style place card offers people the richest experience, presenting them with the most information about a place directly in your map. However, be sure to choose a place card style that fits in the context of your map. For example, if your app displays a small map with many annotations, consider using the compact callout style for a space-saving presentation that shows place information while maintaining the context of the other places that you specify in your map." + }, + { + "type": "paragraph", + "text": "Make sure your place card looks great on different devices and window sizes. If you choose to specify a style, ensure that the content in your place card remains viewable on different devices and as window sizes change. For full callout style place cards, you can set a minimum width to prevent text from overflowing on smaller devices." + }, + { + "type": "paragraph", + "text": "Avoid duplicating information. Consider what information you already display in your app or website when you choose a place card style. For example, the full callout style place card might display information that your app already shows. In this case, the compact callout or caption style might be a better complement." + }, + { + "type": "paragraph", + "text": "Keep the location on your map visible when displaying a place card. This helps people maintain a sense of where the location is on your map while getting detailed place information. You can set an offset distance for your place card and point it to the selected location. For developer guidance, see offset(_:), accessoryOffset, and selectionAccessoryOffset." + } + ] + }, + { + "heading": "Adding place cards outside of a map", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "You can also display place information outside of a map in your app or website. For example, you might want to display a list of places rather than a map, like in search results or a store locator, and present a place card when people select one. For developer guidance, see mapItemDetailSelectionAccessory(_:), mapItemDetail(_:), and PlaceDetail." + }, + { + "type": "important", + "text": "ImportantIf you don’t display a place card directly within a map view, you must include a map in the place card. For developer guidance, see mapItemDetailSheet(item:displaysMap:) and init(mapItem:displaysMap:)." + }, + { + "type": "paragraph", + "text": "Use location-related cues in surrounding content to help communicate that people can open a place card. For example, you can display place names and addresses alongside a button for more details to help indicate that people can interact with it to get place information. For a space-efficient design, you can include a map pin icon with a place name to help communicate that people can open a place card." + } + ] + }, + { + "heading": "Indoor maps", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apps connected with specific venues like shopping malls and stadiums can design custom interactive maps that help people locate and navigate to indoor points of interest. Indoor maps can include overlays that highlight specific areas, such as rooms, kiosks, and other locations. They can also include text labels, icons, and routes." + }, + { + "type": "paragraph", + "text": "Adjust map detail based on the zoom level. Too much detail can cause a map to appear cluttered. Show large areas like rooms and buildings at all zoom levels. Then, progressively add more detailed features and labels as the map is zoomed in. An airport map might show only terminals and gates when zoomed out, but reveal individual stores and restrooms when zoomed in." + }, + { + "type": "paragraph", + "text": "Use distinctive styling to differentiate the features of your map. Using color along with icons can help distinguish different types of areas, stores, and services, and make it easy for people to quickly find what they’re looking for." + }, + { + "type": "paragraph", + "text": "Offer a floor picker if your venue includes multiple levels. A floor picker lets people quickly jump between floors. If you implement this feature, keep floor numbers concise for simplicity. In most cases, a list of floor numbers — rather than floor names — is sufficient." + }, + { + "type": "paragraph", + "text": "Include surrounding areas to provide context. Adjacent streets, playgrounds, and other nearby locations can all help orient people when they use your map. If these areas are noninteractive, use dimming and a distinct color to make them appear supplemental." + }, + { + "type": "paragraph", + "text": "Consider supporting navigation between your venue and nearby transit points. Make it easy to enter and exit your venue by offering routing to and from nearby bus stops, train stations, parking lots, garages, and other transit locations. You might also offer a way for people to quickly switch over to Apple Maps for additional navigation options." + }, + { + "type": "paragraph", + "text": "Limit scrolling outside of your venue. This can help people avoid getting lost when they swipe too hard on your map. When possible, keep at least part of your indoor map visible onscreen at all times. To help people stay oriented, you may need to adjust the amount of scrolling you permit based on the zoom level." + }, + { + "type": "paragraph", + "text": "Design an indoor map that feels like a natural extension of your app. Don’t try to replicate the appearance of Apple Maps. Instead, make sure area overlays, icons, and text match the visual style of your app. For guidance, see Indoor Mapping Data Format." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." + } + ] + }, + { + "heading": "watchOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Apple Watch, maps are static snapshots of geographic locations. Place a map in your interface at design time and show the appropriate region at runtime. The displayed region isn’t interactive; tapping it opens the Maps app on Apple Watch. You can add up to five annotations to a map to highlight points of interest or other relevant information. For developer guidance, see WKInterfaceMap." + }, + { + "type": "paragraph", + "text": "Fit the map interface element to the screen. The entire element needs to be visible on the Apple Watch display without requiring scrolling." + }, + { + "type": "paragraph", + "text": "Show the smallest region that encompasses the points of interest. The content within a map interface element doesn’t scroll, so all key content must be visible within the displayed region." + }, + { + "type": "paragraph", + "text": "For developer guidance, see WKInterfaceMap." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "MapKit" + }, + { + "type": "paragraph", + "text": "MapKit JS" + }, + { + "type": "paragraph", + "text": "Indoor Mapping Data Format" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 18, 2024", + "Added guidance for place cards and included additional artwork." + ], + [ + "September 12, 2023", + "Added artwork." + ], + [ + "September 23, 2022", + "Added guidelines for presenting custom information, refined best practices, and consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/maps#Best-practices" + }, + { + "title": "Custom information", + "url": "/design/human-interface-guidelines/maps#Custom-information" + }, + { + "title": "Place cards", + "url": "/design/human-interface-guidelines/maps#Place-cards" + }, + { + "title": "Displaying place cards in a map", + "url": "/design/human-interface-guidelines/maps#Displaying-place-cards-in-a-map" + }, + { + "title": "sheet", + "url": "https://developer.apple.com/design/human-interface-guidelines/sheets" + }, + { + "title": "Adding place cards outside of a map", + "url": "/design/human-interface-guidelines/maps#Adding-place-cards-outside-of-a-map" + }, + { + "title": "Indoor maps", + "url": "/design/human-interface-guidelines/maps#Indoor-maps" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/maps#Platform-considerations" + }, + { + "title": "watchOS", + "url": "/design/human-interface-guidelines/maps#watchOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/maps#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/maps#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/maps#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/maps#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "NFC", + "url": "https://developer.apple.com/design/human-interface-guidelines/nfc", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "iOS apps running on supported devices can use NFC scanning to read data from electronic tags attached to real-world objects. For example, a person can scan a toy to connect it with a video game, a shopper can scan an in-store sign to access coupons, or a retail employee can scan products to track inventory." + } + ] + }, + { + "heading": "In-app tag reading", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "An app can support single- or multiple-object scanning when the app is active, and display a scanning sheet whenever people are about to scan something." + }, + { + "type": "paragraph", + "text": "Don’t encourage people to make contact with physical objects. To scan a tag, an iOS device must simply be within close proximity of the tag. It doesn’t need to actually touch the tag. Use terms like scan and hold near instead of tap and touch when asking people to scan objects." + }, + { + "type": "paragraph", + "text": "Use approachable terminology. Near-field communication may be unfamiliar to some people. To make it approachable, avoid referring to technical, developer-oriented terms like NFC, Core NFC, Near-field communication, and tag. Instead, use friendly, conversational terms that most people will understand." + }, + { + "type": "table", + "rows": [ + [ + "Use", + "Don’t use" + ], + [ + "Scan the [object name].", + "Scan the NFC tag." + ], + [ + "Hold your iPhone near the [object name] to learn more about it.", + "To use NFC scanning, tap your phone to the [object]." + ] + ] + }, + { + "type": "paragraph", + "text": "Provide succinct instructional text for the scanning sheet. Provide a complete sentence, in sentence case, with ending punctuation. Identify the object to scan, and revise the text appropriately for subsequent scans. Keep the text short to avoid truncation." + }, + { + "type": "table", + "rows": [ + [ + "First scan", + "Subsequent scans" + ], + [ + "Hold your iPhone near the [object name] to learn more about it.", + "Now hold your iPhone near another [object name]." + ] + ] + } + ] + }, + { + "heading": "Background tag reading", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Background tag reading lets people scan tags quickly any time, without needing to first open your app and initiate scanning. On devices that support background tag reading, the system automatically looks for nearby compatible tags whenever the screen is illuminated. After detecting and matching a tag with an app, the system shows a notification that the people can tap to send the tag data to the app for processing. Note that background reading isn’t available when an NFC scanning sheet is visible, Wallet or Apple Pay are in use, cameras are in use, the device is in Airplane Mode, and the device is locked after a restart." + }, + { + "type": "paragraph", + "text": "Support both background and in-app tag reading. Your app must still provide an in-app way to scan tags, for people with devices that don’t support background tag reading." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Core NFC" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "In-app tag reading", + "url": "/design/human-interface-guidelines/nfc#In-app-tag-reading" + }, + { + "title": "Background tag reading", + "url": "/design/human-interface-guidelines/nfc#Background-tag-reading" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/nfc#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/nfc#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/nfc#Developer-documentation" + } + ], + "image_count": 0 + }, + { + "title": "Photo editing", + "url": "https://developer.apple.com/design/human-interface-guidelines/photo-editing", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Edits are always saved in the Photos app as new files, safely preserving the original versions." + }, + { + "type": "paragraph", + "text": "To access a photo editing extension, a photo must be in edit mode. While in edit mode, tapping the extension icon in the toolbar displays an action menu of available editing extensions. Selecting one displays the extension’s interface in a modal view containing a top toolbar. Dismissing this view confirms and saves the edit, or cancels it and returns to the Photos app." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Confirm cancellation of edits. Editing a photo or video can be time consuming. If someone taps the Cancel button, don’t immediately discard their changes. Ask them to confirm that they really want to cancel, and inform them that any edits will be lost after cancellation. There’s no need to show this confirmation if no edits have been made yet." + }, + { + "type": "paragraph", + "text": "Don’t provide a custom top toolbar. Your extension loads within a modal view that already includes a toolbar. Providing a second toolbar is confusing and takes space away from the content being edited." + }, + { + "type": "paragraph", + "text": "Let people preview edits. It’s hard to approve an edit if you can’t see what it looks like. Let people see the result of their work before closing your extension and returning to the Photos app." + }, + { + "type": "paragraph", + "text": "Use your app icon for your photo editing extension icon. This instills confidence that the extension is in fact provided by your app." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, or macOS. Not supported in tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "App extensions" + }, + { + "type": "paragraph", + "text": "PhotoKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/photo-editing#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/photo-editing#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/photo-editing#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/photo-editing#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/photo-editing#Videos" + } + ], + "image_count": 0 + }, + { + "title": "ResearchKit", + "url": "https://developer.apple.com/design/human-interface-guidelines/researchkit", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The ResearchKit framework provides predesigned screens and transitions that make it easy to design and build an engaging custom research app. For developer guidance, see Research & Care > ResearchKit." + }, + { + "type": "paragraph", + "text": "These guidelines are for informational purposes only and don’t constitute legal advice. Contact an attorney to obtain advice with respect to the development of a research app and any applicable laws." + } + ] + }, + { + "heading": "Creating the onboarding experience", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When opening a research app for the first time, people encounter a series of screens that introduce them to the study, determine their eligibility to participate, request permission to proceed with the study, and, when appropriate, grant access to personal data. These screens aren’t typically revisited once they’ve been completed, so clarity is essential." + }, + { + "type": "paragraph", + "text": "Always display the onboarding screens in the correct order." + } + ] + }, + { + "heading": "1. Introduction", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Provide an introduction that informs and provides a call to action. Clearly describe the subject and purpose of your study. Also allow existing participants to quickly log in and continue an in-progress study." + } + ] + }, + { + "heading": "2. Determine eligibility", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Determine eligibility as soon as possible. People don’t need to move on to the consent section if they’re not eligible for the study. Only present eligibility requirements that are necessary for your study. Use simple, straightforward language that describes the requirements, and make it easy to enter information." + } + ] + }, + { + "heading": "3. Get informed consent", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Make sure participants understand your study before you get their consent. ResearchKit helps you make the consent process concise and friendly, while still allowing you to incorporate into the consent any legal requirements or requirements set by an institutional review board or ethics review board. Make sure that your app complies with the applicable App Store Guidelines, including the consent requirements. Typically, the consent section explains how the study works, ensures that participants understand the study and their responsibilities, and gets the participant’s consent." + }, + { + "type": "paragraph", + "text": "Break a long consent form into easily digestible sections. Each section can cover one aspect of the study, such as data gathering, data use, potential benefits, possible risks, time commitment, how to withdraw, and so on. For each section, use simple, straightforward language to provide a high-level overview. If necessary, provide a more detailed explanation of the section that participants can read by tapping a Learn More button. Participants need to be able to view the entire consent form before they agree to participate." + }, + { + "type": "paragraph", + "text": "If it makes sense, provide a quiz that tests the participant’s understanding. You might do this for questions the participant would otherwise be asked when obtaining consent in person." + }, + { + "type": "paragraph", + "text": "Get the participant’s consent and, if appropriate, some contact information. After agreeing to join the study, participants receive a confirmation dialog, followed by screens in which they provide their signature and contact details. Most research apps email participants a PDF version of the consent form for their records." + } + ] + }, + { + "heading": "4. Request permission to access data", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Get permission to access the participant’s device or data, and to send notifications. Clearly explain why your research app needs access to location, Health, or other data, and don’t request access to data that isn’t critical to your study. If your app requires it, also ask for permission to send notifications to the participant’s device." + } + ] + }, + { + "heading": "Conducting research", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "To get input from participants, your study might use surveys, active tasks, or a combination of both. Depending on the architecture of your study, participants may interact with each section multiple times or only once." + }, + { + "type": "paragraph", + "text": "Create surveys that keep participants engaged. ResearchKit provides many customizable screens you can use in your surveys, and makes it easy to present questions that require different types of answers, such as true or false, multiple choice, dates and times, sliding scales, and open-ended text entry. As you use ResearchKit screens to design a survey, follow these guidelines to provide a great experience:" + }, + { + "type": "list", + "items": [ + "Tell participants how many questions there are and about how long the survey will take.", + "Use one screen per question.", + "Show participants their progress in the survey.", + "Keep the survey as short as possible. Several short surveys tend to work better than one long survey.", + "For questions that require some additional explanation, use the standard font for the question and a slightly smaller font for the explanatory text.", + "Tell participants when the survey is complete." + ] + }, + { + "type": "paragraph", + "text": "Make active tasks easy to understand. An active task requires the participant to engage in an activity, such as speaking into the microphone, tapping fingers on the screen, walking, or performing a memory test. Follow these guidelines to encourage participants to perform an active task and give them the best chance of success:" + }, + { + "type": "list", + "items": [ + "Describe how to perform the task using clear, simple language.", + "Explain any requirements, such as if the task must be performed at a particular time or under specific circumstances.", + "Make sure participants can tell when the task is complete." + ] + } + ] + }, + { + "heading": "Managing personal information and providing encouragement", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "ResearchKit offers a profile screen you can use to let participants manage personal information while they’re in your research app. It’s also a good idea to design a custom screen that motivates people and gives them a way to track progress in the study. Ideally, both screens are accessible at all times in your app." + }, + { + "type": "paragraph", + "text": "Use a profile to help participants manage personal data related to your study. A profile screen can let people edit data that might change during the course of the study — such as weight or sleep habits — and remind them of upcoming activities. A profile screen can also provide an easy way to leave a study and view important information, such as the consent document and privacy policy." + }, + { + "type": "paragraph", + "text": "Use a dashboard to show progress and motivate participants to continue. If appropriate for your study, use a dashboard to provide encouraging feedback, such as daily progress, weekly assessments, results from specific activities, and even results that compare the participant’s results with aggregated results from others in the study." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Research & Care > ResearchKit" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Research & Care > Developers" + }, + { + "type": "paragraph", + "text": "Protecting user privacy — HealthKit" + }, + { + "type": "paragraph", + "text": "ResearchKit GitHub project" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 12, 2023", + "Updated artwork." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Creating the onboarding experience", + "url": "/design/human-interface-guidelines/researchkit#Creating-the-onboarding-experience" + }, + { + "title": "1. Introduction", + "url": "/design/human-interface-guidelines/researchkit#1-Introduction" + }, + { + "title": "2. Determine eligibility", + "url": "/design/human-interface-guidelines/researchkit#2-Determine-eligibility" + }, + { + "title": "3. Get informed consent", + "url": "/design/human-interface-guidelines/researchkit#3-Get-informed-consent" + }, + { + "title": "4. Request permission to access data", + "url": "/design/human-interface-guidelines/researchkit#4-Request-permission-to-access-data" + }, + { + "title": "Conducting research", + "url": "/design/human-interface-guidelines/researchkit#Conducting-research" + }, + { + "title": "Managing personal information and providing encouragement", + "url": "/design/human-interface-guidelines/researchkit#Managing-personal-information-and-providing-encouragement" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/researchkit#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/researchkit#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/researchkit#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/researchkit#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/researchkit#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/researchkit#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "SharePlay", + "url": "https://developer.apple.com/design/human-interface-guidelines/shareplay", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "The system synchronizes app playback on all participating devices to support seamless media and content sharing that lets everyone enjoy the experience simultaneously. In visionOS, SharePlay helps people enjoy these experiences while they’re together in the same virtual space." + }, + { + "type": "paragraph", + "text": "When someone shares content during a FaceTime call, the system asks each participant to launch the app to begin the experience. If people don’t have the app installed, the SharePlay alert encourages them to download it from the App Store. If you make the platform-specific versions of your app available as a Universal Purchase, people can make one purchase and use your app and their in-app purchases across all the platforms you support." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Let people know that you support SharePlay. People often expect media playback experiences to be shareable, so indicate this capability in your interface. For example, you can use the shareplay SF Symbol to identify the content or experiences in your app that support SharePlay." + }, + { + "type": "paragraph", + "text": "If part of your app requires a subscription, consider ways to help nonsubscriber participants quickly join a group activity. For example, you might offer temporary or provisional access to nonsubscribers or let an existing subscriber send a one-time pass to a friend. To make it easy for family members to share your content in a SharePlay experience, you can support Family Sharing. If people can start a subscription during a SharePlay experience, present a streamlined version of your sign-up flow so they can join the activity without making others wait. For guidance, see Auto-renewable subscriptions." + }, + { + "type": "paragraph", + "text": "Support Picture in Picture (PiP) when possible. On iPhone and iPad, people can open a shared video in a PiP window. On a Mac, a shared video opens in a background window that people can move into the foreground when they want to watch." + }, + { + "type": "paragraph", + "text": "Use the term SharePlay correctly. You can use SharePlay as a noun — as in “Join SharePlay” — and also as a verb when describing a direct action in your interface. For example, in a button or sheet that lets people share a movie-viewing activity, you can use a phrase like “SharePlay Movie.” Avoid using an adjective with SharePlay; for example, in your visionOS app, don’t add terms like virtual or spatial. Avoid changing the term SharePlay in any way; for example, don’t use variations like SharePlayed, SharePlays, or SharePlaying." + } + ] + }, + { + "heading": "Sharing activities", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "An activity is an app-defined type of shareable experience. For example, an app that lets people view videos might define a separate activity for viewing each type of content — like movies, TV shows, and uploaded videos — and display a different description for each activity. You can define as many different activities as make sense in your app. For developer guidance, see Defining your app’s SharePlay activities." + }, + { + "type": "paragraph", + "text": "Briefly describe each activity. When people receive an invitation to participate in an activity, your description helps them understand the experience they’re about to share. For example, a video-viewing app might associate its descriptive movie view with a movie-viewing activity. In this case, the descriptive view might display a movie’s title, a plot summary, and a poster image. Write a simple, meaningful description that’s short enough to avoid truncation." + }, + { + "type": "paragraph", + "text": "Make it easy to start sharing an activity. If there’s no session available when people start a shareable activity, you can present UI that lets them start a group activity. In response, the system asks people if they want to share or continue the experience solo." + }, + { + "type": "paragraph", + "text": "Help people prepare to join a session before displaying the activity. For example, if people must log in, download content, or make a payment before they can participate, display views that help them perform these tasks before showing the activity UI. Make these tasks as simple and effortless as possible so people can join the group activity quickly." + }, + { + "type": "paragraph", + "text": "When possible, defer app tasks that might delay a shared activity. For example, if your app needs to know a participant’s profile, consider asking for this information at a convenient time, like when playback pauses or finishes." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." + } + ] + }, + { + "heading": "visionOS", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People expect most visionOS apps to support SharePlay. While wearing Apple Vision Pro, people choose the Spatial option in FaceTime to share content and activities with others." + }, + { + "type": "paragraph", + "text": "In a shared activity, FaceTime can show representations of other participants — called spatial Personas — within each wearer’s space, making everyone feel like they’re sharing the same experience in the same place. During a shared experience in FaceTime, people can interact with each other in natural ways through their spatial Personas. For example, people can speak or gesture directly to others, tell when someone is paying attention to them, and know which person is using a shared tool or resource." + }, + { + "type": "paragraph", + "text": "visionOS uses the concept of shared context to describe the characteristics of a shared activity that help people feel physically present with others while connecting over the same content. A shared context helps give people confidence that they’re experiencing the same thing as everyone else." + }, + { + "type": "paragraph", + "text": "When people feel that they’re truly sharing an experience, social dynamics can encourage authentic, intuitive interactions. For example, people can communicate verbally and nonverbally to make plans, take turns, and share resources." + }, + { + "type": "note", + "text": "NoteDuring a shared activity, the system helps preserve people’s privacy by obscuring some visual details about wearers. In addition, a person can adjust their spatial Persona if they want. Although the system can place spatial Personas shoulder to shoulder and it supports shared gestures like a handshake or “high five,” spatial Personas remain apart." + }, + { + "type": "paragraph", + "text": "Choose the spatial Persona template that suits your shared activity. When you design a shared activity, you can use a spatial Persona template to specify a layout for arranging spatial Personas in the shared activity space. The system provides three spatial Persona templates: side-by-side, surround, and conversational." + }, + { + "type": "paragraph", + "text": "The side-by-side template places participants next to each other along a curved line segment, all facing the shared content. The side-by-side template gives everyone a great view of the content, making it a good choice for helping people watch media together. Because people aren’t facing each other in this arrangement, the side-by-side template can encourage less nonverbal interaction than other spatial Persona templates." + }, + { + "type": "paragraph", + "text": "The system-applied surround template arranges participants all the way around the shared content in the center. This spatial Persona template works especially well when the content is 3D, because each participant views it from a different angle. In the surround template, participants face each other as if they were grouped around a table, promoting both verbal and nonverbal interactions." + }, + { + "type": "paragraph", + "text": "The conversational template also groups participants around a center point, but places your content along the circle, not at its center. Because of this position, not everyone has the same view of your content, and it might not be convenient for everyone to interact with it. Consider using the conversational arrangement if your experience is more about people being together while your app performs a task in the background like playing music." + }, + { + "type": "paragraph", + "text": "For developer guidance, see SystemCoordinator and SpatialTemplatePreference." + }, + { + "type": "paragraph", + "text": "Be prepared to launch directly into your shared activity. When one person shares your activity with others on a FaceTime call, the system minimizes friction by automatically launching your app for everyone. In this scenario, you want to avoid displaying any windows that aren’t related to the shared activity. For example, if people need to sign in before joining the activity, be sure to present this task in an autodismissible window that disappears as soon as people finish providing the required input." + }, + { + "type": "paragraph", + "text": "Help people enter a shared activity together, but don’t force them. When one participant changes their level of immersion, the system tells you so you can synchronize the experience for everyone. Before synchronizing, check whether changing a person’s level of immersion would disrupt their current task; if it would, offer them the choice to join the updated experience. For example, if someone is editing content in an unshared window, you might present an alert that lets them choose to transition. For guidance, see Immersive experiences." + }, + { + "type": "paragraph", + "text": "Smoothly update a shared activity when new participants join. When someone joins an in-progress activity, you need to integrate them without disrupting the experience for everyone else. For example, it’s important to update shared immersive content to keep all participants synchronized. Also, consider designing ways to accommodate up to five participants in your arrangement, updating their positions as necessary." + } + ] + }, + { + "heading": "Maintaining a shared context", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "When your shared activity runs in a Full Space, the system helps your app maintain a shared context by using a single coordinate system to arrange your content and all participants, automatically synchronizing the size, position, and orientation of your app for each person. You’re responsible for displaying objects, playing sounds, and supporting interactions in ways that enhance the feeling of sharing the experience." + }, + { + "type": "paragraph", + "text": "Make sure everyone views the same state of your app. If your app has more than one state — such as a media app that provides both minimal and theater-like viewing modes — you need to avoid letting different participants view different states, because doing so can diminish people’s sense of being together in a shared space. The exception to this is when someone needs to temporarily exit a shared activity; for guidance, see Adjusting a shared context." + }, + { + "type": "paragraph", + "text": "Use Spatial Audio to enrich your shared activity. Playing Spatial Audio can help you strengthen the realism of the shared experience. For guidance, see Playing audio." + }, + { + "type": "paragraph", + "text": "When possible, let people discover natural, social solutions to confusions or conflicts that might arise during a shared experience. For example, if only one participant at a time can use a virtual tool, avoid displaying UI, like tool-use controls or notifications, and instead let people speak or gesture to the group when they want to use the tool. If conflicts can arise during your shared activity — for example, if multiple people try to change the same content at the same time — consider implementing a simple rule, like last change wins, and letting people use the rule to define behavior that’s acceptable to the group." + }, + { + "type": "paragraph", + "text": "Help people keep their private and shared content separate. By default, the system clearly differentiates a shared window from windows that aren’t shared. For example, when people use Music to listen together, the shared Music window appears as a new window for everyone, while any individual’s open library window remains separate and unshared. If your app can open multiple windows, help people share the one they want and make it easy for them to distinguish shared from unshared windows. If possible, also let people drag content they want to share from a private window to a shared one." + }, + { + "type": "paragraph", + "text": "Content in a TV window is private by default." + }, + { + "type": "paragraph", + "text": "People can select the Share button to choose whether, and with whom, to share the viewing experience." + }, + { + "type": "paragraph", + "text": "When sharing, the app clearly communicates the shared state." + } + ] + }, + { + "heading": "Adjusting a shared context", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Sometimes, it makes sense to adjust the shared context of a shared activity so each participant can customize their experience, such as for comfort or accessibility. In other situations, strictly maintaining a shared context might decrease people’s enjoyment of the experience. For example, when content has only one ideal viewing angle, each participant might need their own." + }, + { + "type": "paragraph", + "text": "Let people personalize their experience without changing the experience for others. For example, people might need to adjust various settings, like volume or subtitles, to make views and interactions accessible or make themselves more comfortable." + }, + { + "type": "paragraph", + "text": "When sharing, two people watching the same video can choose separately whether to turn subtitles on or off." + }, + { + "type": "paragraph", + "text": "Consider when to give each participant a unique view of the shared content. Some content looks best when people view it from a specific perspective. For example, people can share a Spatial Capture in a standard window with other people’s spatial Personas visible around it. However, to perceive the depth in a Spatial Capture, each person needs to view it from the right angle. In this scenario, a person could temporarily transition to a Full Space that hides other participants and ensures the right viewing angle for them, even while everyone else continues to view the standard window and each other. If it makes sense to provide per-person versions of your shared content, be sure to continue synchronizing people’s positions and your app context to maintain the shared experience." + }, + { + "type": "paragraph", + "text": "Make it easy for people to exit and rejoin a shared activity. Sometimes, people need to perform an unrelated task in your app or a different one, or engage with their physical surroundings. When this happens, you need to present a control or other component that lets people quickly rejoin the shared activity. In addition, you might want to continue displaying the shared content so people can stay informed about the ongoing shared experience while they’re hiding their spatial Persona." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Auto-renewable subscriptions" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Group Activities" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "December 5, 2023", + "Added artwork for visionOS." + ], + [ + "June 21, 2023", + "Updated to include guidance for visionOS." + ], + [ + "December 19, 2022", + "Clarified guidance for helping nonsubscribers join a group activity." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/shareplay#Best-practices" + }, + { + "title": "Family Sharing", + "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase#Supporting-Family-Sharing" + }, + { + "title": "Auto-renewable subscriptions", + "url": "/design/human-interface-guidelines/in-app-purchase#Auto-renewable-subscriptions" + }, + { + "title": "Sharing activities", + "url": "/design/human-interface-guidelines/shareplay#Sharing-activities" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/shareplay#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/shareplay#visionOS" + }, + { + "title": "Immersive experiences", + "url": "/design/human-interface-guidelines/immersive-experiences" + }, + { + "title": "Maintaining a shared context", + "url": "/design/human-interface-guidelines/shareplay#Maintaining-a-shared-context" + }, + { + "title": "Adjusting a shared context", + "url": "/design/human-interface-guidelines/shareplay#Adjusting-a-shared-context" + }, + { + "title": "Playing audio", + "url": "/design/human-interface-guidelines/playing-audio" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/shareplay#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/shareplay#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/shareplay#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/shareplay#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/shareplay#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "ShazamKit", + "url": "https://developer.apple.com/design/human-interface-guidelines/shazamkit", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You can use ShazamKit to provide features like:" + }, + { + "type": "list", + "items": [ + "Enhancing experiences with graphics that correspond with the genre of currently playing music", + "Making media content accessible to people with hearing disabilities by providing closed captions or sign language that syncs with the audio", + "Synchronizing in-app experiences with virtual content in contexts like online learning and retail" + ] + }, + { + "type": "paragraph", + "text": "If you need the device microphone to get audio samples for your app to recognize, you must request access to it. As with all types of permission requests, it’s important to help people understand why you’re asking for access. For guidance, see Privacy." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "After you receive permission to access the microphone for features that use ShazamKit, follow these guidelines." + }, + { + "type": "paragraph", + "text": "Stop recording as soon as possible. When people allow your app to record audio for recognition, they don’t expect the microphone to stay on. To help preserve privacy, only record for as long as it takes to get the sample you need." + }, + { + "type": "paragraph", + "text": "Let people opt in to storing your app’s recognized songs to their iCloud library. If your app can store recognized songs to iCloud, give people a way to first approve this action. Even though both the Music Recognition control and the Shazam app show your app as the source of the recognized song, people appreciate having control over which apps can store content in their library." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "ShazamKit" + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Privacy", + "url": "/design/human-interface-guidelines/privacy" + }, + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/shazamkit#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/shazamkit#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/shazamkit#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/shazamkit#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/shazamkit#Videos" + } + ], + "image_count": 0 + }, + { + "title": "Sign in with Apple", + "url": "https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Supporting Sign in with Apple lets people use the Apple Account they already have to sign in or sign up, and skip filling out forms, verifying email addresses, and choosing passwords. In cases where you choose to ask for a name and email address, people have the option to share a unique, random email address that automatically relays messages to their personal email address. For developer guidance, see Authentication Services." + }, + { + "type": "paragraph", + "text": "You can offer Sign in with Apple in every version of your app or website across all platforms — including non-Apple platforms." + }, + { + "type": "paragraph", + "text": "Sign in with Apple makes it easy for people to authenticate with Face ID, Touch ID, or Optic ID and has two-factor authentication built in for an added layer of security. Apple doesn’t use Sign in with Apple to profile people or their activity in apps." + } + ] + }, + { + "heading": "Offering Sign in with Apple", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Follow these guidelines to offer Sign in with Apple when it’s most convenient for people." + }, + { + "type": "paragraph", + "text": "Ask people to sign in only in exchange for value. People need to understand why you’re asking them to sign in, so it can work well to display a brief, approachable description of sign-in benefits. For example, you might want to tell people that signing in lets them personalize the app experience, access additional features, or synchronize data." + }, + { + "type": "paragraph", + "text": "Delay sign-in as long as possible. People often abandon apps when they’re forced to sign in before doing anything useful. Give them a chance to familiarize themselves with your app before making a commitment. For example, a live-streaming app could let people explore available content before signing in to stream something." + }, + { + "type": "paragraph", + "text": "If you require an account, ask people to set it up before offering any sign-in options. Start by explaining the reasons for requiring an account. Then, after people complete account setup, let them choose a convenient way to sign in to their new account by offering Sign in with Apple and any other sign-in methods you support." + }, + { + "type": "paragraph", + "text": "Consider letting people link an existing account to Sign in with Apple. When you support this type of linking, people can get the convenience of using Sign in with Apple while maintaining access to the information in an account they’ve already set up. You can offer account linking before or after people sign in to their existing account. For example:" + }, + { + "type": "list", + "items": [ + "If people share an email address through Sign in with Apple and it matches the address in an existing account, you can suggest that they link Sign in with Apple to that account.", + "If people used an existing user name and password to sign in, you can display an account-linking suggestion in their account’s settings view or another logical place." + ] + }, + { + "type": "paragraph", + "text": "In a commerce app, wait until after people make a purchase before asking them to create an account. If you support a guest checkout system, give people a quick way to create an account after the transaction completes. For example, if you support Apple Pay, let people create an account on the order confirmation page. In cases where people have already provided their name and email address during the Apple Pay transaction, you don’t need to ask for this information." + }, + { + "type": "paragraph", + "text": "As soon as Sign in with Apple completes, welcome people to their new account. Help people use their new account right away; don’t delay the experience by asking for information that isn’t required." + }, + { + "type": "paragraph", + "text": "Indicate when people are currently signed in. You can help people confirm their sign-in method by displaying a phrase like “Using Sign in with Apple” in places like a settings or account interface." + } + ] + }, + { + "heading": "Collecting data", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People appreciate Sign in with Apple for its privacy and convenience. Although some apps or websites may require additional information — such as a date of birth or a region of residence — it’s essential to minimize your requests for data as people set up an account. Build on the trust that people have in Sign in with Apple by describing why you need additional data and clearly displaying the data you receive." + }, + { + "type": "paragraph", + "text": "Clarify whether the additional data you request is required or just recommended. If the data is legally or contractually required — such as an agreement to terms of service, country or region of residence, birth date, or information required by a region’s real-identity laws — make sure people understand that they must supply the additional information to complete the setup of their account. If additional data isn’t required but can improve the user experience, make sure people know the request is optional and help them understand the benefits of providing the information." + }, + { + "type": "paragraph", + "text": "Don’t ask people to supply a password. A key benefit of Sign in with Apple is that people don’t have to create and memorize additional passwords. Unless people have stopped using Sign in with Apple with your app or website, don’t ask for a password." + }, + { + "type": "paragraph", + "text": "Avoid asking for a personal email address when people supply a private relay address. Using Sign in with Apple, people can choose to share a private relay address that automatically forwards messages to their verified personal email account. It’s essential to respect this choice and avoid overriding it by asking for a personal email address. If you present customer service, retail, or other experiences that request identification via email address, you can:" + }, + { + "type": "list", + "items": [ + "Make sure that people can view their private relay address in your app or website", + "Direct people to Settings > Apple Account > Password & Security > Apps using Apple Account to retrieve their private relay address", + "Use other identifying values, like an order number or phone number collected as part of a purchase" + ] + }, + { + "type": "paragraph", + "text": "Give people a chance to engage with your app before asking for optional data. As people use your app, you can help them discover places where they can benefit from sharing more information with you. For example, you might suggest that they provide a contact phone number if they want real-time text updates, or social network information if they want to play games with friends. If people choose not to provide optional information, don’t prevent them from accessing their account or using all the features of your app." + }, + { + "type": "paragraph", + "text": "Be transparent about the data you collect. People value knowing how you use the data that they share with you. One way you can be transparent is to welcome people by using the name or email address they shared. Doing this helps establish how you use this information and, for a relay address, shows people where to find it in the future. If you don’t display all the data that people provide, they are likely to wonder why you asked for it." + } + ] + }, + { + "heading": "Displaying buttons", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Apple provides several Sign in with Apple buttons you can use to let people set up an account and sign in. If necessary, you can create a custom button to offer Sign in with Apple; for guidelines, see Creating a custom Sign in with Apple button." + }, + { + "type": "paragraph", + "text": "Prominently display a Sign in with Apple button. Make a Sign in with Apple button no smaller than other sign-in buttons, and avoid making people scroll to see the button." + } + ] + }, + { + "heading": "Using the system-provided buttons", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When you use the system-provided APIs to create a Sign in with Apple button, you get the following advantages." + }, + { + "type": "list", + "items": [ + "A button that’s guaranteed to use an Apple-approved appearance", + "Assurance that the button’s contents maintain ideal proportions as you change its style", + "Automatic translation of the button’s title into the language specified by the device", + "Support for configuring the button’s corner radius to match the style of your UI (iOS, macOS, and web)", + "A system-provided alternative text label that lets VoiceOver describe the button" + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see ASAuthorizationAppleIDButton (iOS, macOS, and tvOS), WKInterfaceAuthorizationAppleIDButton (watchOS), and Displaying Sign in with Apple buttons on the web. You can also visit Sign in with Apple button to view and adjust live previews of web-based buttons and get the code." + }, + { + "type": "paragraph", + "text": "The system provides several variants of the button title. Depending on the platform on which your content runs, choose the variant that fits the terminology of your sign-in experience and use it consistently throughout your interfaces." + }, + { + "type": "paragraph", + "text": "The following button titles are available for iOS, macOS, tvOS, and the web:" + }, + { + "type": "paragraph", + "text": "For watchOS, the system provides one title:  Sign in." + }, + { + "type": "paragraph", + "text": "Depending on the platform, the system provides up to three options for the appearance of the Sign in with Apple button: white, white with an outline, and black. Choose the appearance that works best with the background on which the button displays." + } + ] + }, + { + "heading": "White", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "The white style is available on all platforms and the web. Use this style on dark backgrounds that provide sufficient contrast." + } + ] + }, + { + "heading": "White with outline", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "The white outlined style is available in iOS, macOS, and the web. Use this style on white or light-color backgrounds that don’t provide sufficient contrast with the white button fill. Avoid using this style on a dark or saturated background, because the black outline can add visual clutter; instead, use the white style to contrast with a dark background." + } + ] + }, + { + "heading": "Black", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "The black style is available on all platforms and the web. Use this style on white or light-color backgrounds that provide sufficient contrast; don’t use it on black or dark backgrounds." + }, + { + "type": "paragraph", + "text": "Unlike the black Sign in with Apple button for other platforms, the watchOS button uses a fill color that’s not fully black. To contrast with the pure black background of Apple Watch, the watchOS button uses the system-defined dark gray appearance." + } + ] + }, + { + "heading": "Button size and corner radius", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adjust the corner radius to match the appearance of other buttons in your app. By default, the Sign in with Apple button has rounded corners. In iOS, macOS, and the web, you can change the corner radius to produce a button with square corners or a capsule-shape button. For developer guidance, see cornerRadius (iOS and macOS) and Displaying Sign in with Apple buttons on the web." + }, + { + "type": "paragraph", + "text": "Minimum corner radius" + }, + { + "type": "paragraph", + "text": "Default corner radius" + }, + { + "type": "paragraph", + "text": "Maximum corner radius" + }, + { + "type": "paragraph", + "text": "Maintain the minimum button size and margin around the button in iOS, macOS, and the web. Be mindful that the button title may vary in length depending on the locale. Use the following values for guidance." + }, + { + "type": "table", + "rows": [ + [ + "Minimum width", + "Minimum height", + "Minimum margin" + ], + [ + "140pt (140px @1x, 280px @2x)", + "30pt (30px @1x, 60px @2x)", + "1/10 of the button’s height" + ] + ] + } + ] + }, + { + "heading": "Creating a custom Sign in with Apple button", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If your interface requires it, you can create a custom Sign in with Apple button for iOS, macOS, or the web. For example, you may want to align logos across multiple sign-in buttons, use buttons that display only a logo, or adjust the button’s font, bezel, or background appearance to coordinate with your UI." + }, + { + "type": "paragraph", + "text": "Always make sure that people can instantly identify your custom button as a Sign in with Apple button. If your custom button differs too much from the standard one, people may not feel comfortable using it to set up an account or sign in. App Review evaluates all custom Sign in with Apple buttons." + }, + { + "type": "paragraph", + "text": "Apple Design Resources provides downloadable Apple logo artwork you can use to create custom Sign in with Apple buttons that display either a logo only or a logo and text. The logo files are available in PNG, SVG, and PDF formats, and the artwork for both types of buttons includes both black and white versions. Here are examples of the black and white logo-only art files, each with a background added for visibility." + }, + { + "type": "paragraph", + "text": "All downloadable logo files include padding that simplifies positioning the logo in a button. Logo-only logo files include horizontal and vertical padding that ensures the correct proportion of the logo relative to the button. In addition to padding that keeps the logo and button correctly proportioned, logo files for buttons with text also include horizontal padding that provides a minimum margin between the logo and the button’s leading edge and title." + }, + { + "type": "paragraph", + "text": "Use only the logo artwork downloaded from Apple Design Resources; never create a custom Apple logo. As you create a custom Sign in with Apple button, follow these guidelines for using the downloadable logo file:" + }, + { + "type": "list", + "items": [ + "Use the logo file to position the Apple logo in a button; never use the Apple logo as a button.", + "Match the height of the logo file to the height of the button.", + "Don’t crop the logo file.", + "Don’t add vertical padding." + ] + }, + { + "type": "paragraph", + "text": "To make sure that your custom button is visually consistent with the system-provided Sign in with Apple button, don’t change the following attributes." + }, + { + "type": "list", + "items": [ + "Titles. Use only Sign in with Apple, Sign up with Apple, or Continue with Apple.", + "General shape. Buttons that combine the logo with text are always rectangular; logo-only buttons can be circular or rectangular.", + "Logo and title colors. Within a button, both items must be either black or white; don’t use custom colors." + ] + }, + { + "type": "paragraph", + "text": "To coordinate with your app design, you can change:" + }, + { + "type": "list", + "items": [ + "Title font. You can also adjust the font’s weight and size.", + "Title case. You can capitalize every letter in the title.", + "Background appearance. The overall color needs to remain black or white. If necessary, you can include a subtle texture or gradient to help the button harmonize with your interface.", + "Button corner radius. You can use a corner radius value that matches the other buttons in your UI.", + "Button bezel and shadow. For example, you can use a stroke to emphasize the button bezel or add a drop shadow." + ] + } + ] + }, + { + "heading": "Custom buttons with a logo and text", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Choose the format of the logo file based on the height of your button. Because SVG and PDF are vector-based formats, you can use these files in buttons of any height. Use the PNG files only in buttons that are 44 points tall, which is the default (and recommended) button height in iOS. Logos are available in small, medium, and large sizes, so you can match logo sizes in all the sign-up buttons you display." + }, + { + "type": "paragraph", + "text": "Prefer the system font for the title — that is, Sign in with Apple, Sign up with Apple, or Continue with Apple. Regardless of the font you choose, the title and button height of your custom button need to use the same proportions that the system uses. Using the system font for example, the title’s font size would be 43% of the button’s height — in other words, the button’s height would be 233% of the title’s font size, rounded to the nearest integer. Here are two examples that show these proportions using different sizes of the system font." + }, + { + "type": "paragraph", + "text": "In general, preserve the capitalization style of the title. By default, all variants of the button title capitalize the first word — that is, Sign or Continue — and Apple; all other letters are lowercase. Avoid changing this style unless your interface uses only uppercase." + }, + { + "type": "paragraph", + "text": "Keep the title and logo vertically aligned within the button. To do this, vertically align the title to the middle of the button, then add the logo image, making sure its height matches the height of the button. Because the logo image includes top and bottom padding, vertically aligning the title in the button ensures that the title, the logo, and the button stay properly aligned." + }, + { + "type": "paragraph", + "text": "Inset the logo if necessary. If you need to horizontally align the Apple logo with other authentication logos, you can adjust the space between the logo and the button’s leading edge." + }, + { + "type": "paragraph", + "text": "Maintain a minimum margin between the title and the right edge of the button. Ensure the margin measures at least 8% of the button’s width." + }, + { + "type": "paragraph", + "text": "Maintain the minimum button size and margin around the button. Be mindful that the button title may vary in length depending on the locale. Use the following values for guidance." + }, + { + "type": "table", + "rows": [ + [ + "Minimum width", + "Minimum height", + "Minimum margin" + ], + [ + "140 pt (140 px @1x, 280 px @2x)", + "30 pt (30 px @1x, 60 px @2x)", + "1/10 of the button’s height" + ] + ] + } + ] + }, + { + "heading": "Custom logo-only buttons", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Choose the format of the logo file based on the size of your button. The downloadable artwork for logo-only buttons is available in SVG, PDF, and PNG formats. Use the vector-based SVG and PDF formats for buttons of any size; use the PNG format only in buttons that measure 44x44 pt." + }, + { + "type": "paragraph", + "text": "Don’t add horizontal padding to a logo-only image. A logo-only Sign in with Apple button always has a 1:1 aspect ratio, and the artwork already includes the correct padding on all sides." + }, + { + "type": "paragraph", + "text": "Use a mask to change the default square shape of the logo-only image. For example, you might want to use a circular or rounded rectangular shape to present all logo-only sign-in buttons. Never crop the Apple-provided artwork to decrease its built-in padding or use the logo by itself, and avoid including additional padding." + }, + { + "type": "paragraph", + "text": "Rounded rectangle mask" + }, + { + "type": "paragraph", + "text": "No mask" + }, + { + "type": "paragraph", + "text": "Circular mask" + }, + { + "type": "paragraph", + "text": "Maintain a minimum margin around the button. Ensure the margin measures at least 1/10 of the button’s height." + } + ] + }, + { + "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": "Sign in with Apple button" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Authentication Services" + }, + { + "type": "paragraph", + "text": "Displaying Sign in with Apple buttons on the web — Sign in with Apple" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "September 14, 2022", + "Refined guidance on supporting existing accounts, helping people set up a new account, and indicating the current sign-in status. Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Offering Sign in with Apple", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Offering-Sign-in-with-Apple" + }, + { + "title": "Collecting data", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Collecting-data" + }, + { + "title": "Displaying buttons", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Displaying-buttons" + }, + { + "title": "Creating a custom Sign in with Apple button", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Creating-a-custom-Sign-in-with-Apple-button" + }, + { + "title": "Using the system-provided buttons", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Using-the-system-provided-buttons" + }, + { + "title": "White", + "url": "/design/human-interface-guidelines/sign-in-with-apple#White" + }, + { + "title": "White with outline", + "url": "/design/human-interface-guidelines/sign-in-with-apple#White-with-outline" + }, + { + "title": "white", + "url": "https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple#White" + }, + { + "title": "Black", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Black" + }, + { + "title": "Button size and corner radius", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Button-size-and-corner-radius" + }, + { + "title": "Custom buttons with a logo and text", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Custom-buttons-with-a-logo-and-text" + }, + { + "title": "Custom logo-only buttons", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Custom-logo-only-buttons" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/sign-in-with-apple#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Siri", + "url": "https://developer.apple.com/design/human-interface-guidelines/siri", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you use SiriKit to define the tasks and actions that your app supports, people can use Siri to perform them even when your app isn’t running. If you’re an accessory maker, you can also help people use Siri to control your accessories by integrating them with HomeKit or AirPlay. Here are some of the ways people can use Siri to interact with your app or accessory:" + }, + { + "type": "list", + "items": [ + "Ask Siri to perform a system-defined task that your app supports, like send a message, play a song, or start a workout.", + "Run a shortcut, which is a way to accelerate actions your app defines through onscreen interactions or by voice.", + "Use the Shortcuts app to adjust what a shortcut does, including combining several actions to perform one multistep shortcut.", + "Tap a suggestion to perform a shortcut with your app (Siri can suggest shortcuts that people might want to perform, based on their current context and the information you provide).", + "Use Siri to control an accessory that integrates with your app." + ] + }, + { + "type": "paragraph", + "text": "Siri works with your products on iPhone, iPad, Mac, Apple Watch, HomePod, and AirPods, so people can use it almost everywhere." + }, + { + "type": "paragraph", + "text": "When you make your app’s tasks available through Siri, you have several opportunities to customize the user experience. At a fundamental level, you customize the flow and functionality of the everyday tasks and actions you support to implement your business requirements. To reinforce this functionality throughout the user experience, you can write dialogue that reflects the style and tone of your company’s communications and design custom UI that incorporates your app’s visual style into the Siri interface." + }, + { + "type": "paragraph", + "text": "As you approach the job of integrating your app with Siri, assess the actions your app performs and learn how people use your app without voice interaction. Then consider the following steps:" + }, + { + "type": "list", + "items": [ + "Identify key tasks in your app that people might want to perform on a regular basis.", + "Drive engagement by telling the system about your app’s key tasks and by supporting suggestions.", + "For actions that people can perform through voice interaction, design functional conversational flows that feel natural.", + "Explore the various ways people might perform your app’s tasks — such as in a hands-free situation — and the devices they might be using, such as Apple Watch or iPad." + ] + } + ] + }, + { + "heading": "Integrating your app with Siri", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Tasks are at the core of your app’s integration with Siri. SiriKit builds on the idea of a person’s intention to perform a task by using the term intent to represent a task an app supports. The communication between your app and Siri is based on the intents — that is, the tasks — your app helps people perform." + }, + { + "type": "paragraph", + "text": "SiriKit defines system intents that represent common tasks — such as sending a message, calling a friend, and starting a workout — and groups related intents into domains. A domain is a category of tasks that Siri knows how to talk about, like messaging, calling, and workouts. For a complete list of domains and the actions in each domain that iOS and watchOS support, see System intents." + }, + { + "type": "paragraph", + "text": "When possible, take advantage of the intents that SiriKit defines. Using system-provided intents can make your job easier, while still giving you opportunities to customize the experience. However, if your app offers tasks that aren’t represented by system-defined intents — like ordering a meal or shopping for groceries — you can create a custom intent (for guidance, see Custom intents)." + } + ] + }, + { + "heading": "A closer look at intents", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When people use Siri to ask questions and perform actions, Siri does the language processing and semantic analysis needed to turn their requests into intents for your app to handle. The exception is the personal phrase that people create to run a shortcut: When people speak the exact phrase, Siri recognizes it without doing additional processing or analysis." + }, + { + "type": "paragraph", + "text": "As a designer, your main job is to present clear, actionable content that helps clarify and streamline the interactions people have with Siri to get things done in your app. Some of these interactions happen while your app and SiriKit communicate about handling the intent, so it’s helpful to be familiar with the related SiriKit terminology. At a high level, your app processes an intent in three phases: resolve, confirm, and handle." + }, + { + "type": "paragraph", + "text": "First, your app and SiriKit must agree on what the request means in the resolve phase. You can think of this phase as the time to ask people for everything your app needs and, if necessary, ask for additional information or clarification. For example, if people ask to send a message to Amy, and they have multiple contacts named Amy, a messaging app can have Siri ask which Amy they mean. Details related to an intent, like a message recipient’s name, are known as parameters. In the resolve phase, you can indicate the parameters that are required to complete an action and those that are optional. For developer guidance, see Resolving the Parameters of an Intent." + }, + { + "type": "paragraph", + "text": "The second phase — called the confirm phase — happens when you have all the information you need to handle the intent. This phase can give people a chance to make sure they want to complete the task. For example, tasks that have financial impact require confirmation. In addition to asking for a person’s consent, you can present an error during this phase if something will prevent your app from completing the action. For example, if people use an app to order an item for pickup when the pickup location is closed, the app can describe why it can’t complete the action right now. Presenting this error during the confirm phase avoids making people wait until they’re paying for the item to find out that their request has failed. For developer guidance, see Confirming the Details of an Intent." + }, + { + "type": "paragraph", + "text": "Third, your app performs the task and tells SiriKit what it actually did in the handle phase. You can provide both visual and textual information that tells people what your app did to handle their request. For example, an app that lets people order coffee might present a receipt that describes the order. Siri can speak or display the information your app provides. For developer guidance, see Handling an Intent." + } + ] + }, + { + "heading": "Provide information about actions and support suggestions", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Most apps support large numbers of actions, but people tend to perform only a handful of them on a regular basis. When you tell the system about people’s regular actions and describe new ones you think they’ll want to perform in the future, Siri can suggest shortcuts for both types of actions when people are likely to be interested in them." + }, + { + "type": "paragraph", + "text": "For example, in an app that’s all about coffee, the most frequent action might be to order a cup of coffee, while less frequent actions might include buying coffee beans or locating a new coffee shop. In this example, the coffee app would share information about the order coffee action so that Siri can suggest a shortcut for this action when people usually want to do it, like weekday mornings. The app could also tell Siri about an action that people haven’t performed yet, but might be interested in — like ordering a new seasonal variation of their favorite coffee — so that Siri might suggest a shortcut for this action." + }, + { + "type": "paragraph", + "text": "Siri can use signals like location, time of day, and type of motion (such as walking, running, or driving), to intelligently predict just the right time and place to suggest actions from your app. Depending on the information your app shares and people’s current context, Siri can offer shortcut suggestions on the lock screen, in search results, or on the Siri watch face. Siri can also use some types of information to suggest actions that system apps support, such as using Calendar to add an event shared by your app. Here are some example scenarios." + }, + { + "type": "list", + "items": [ + "Shortly before 7:30 a.m., Siri might suggest the order coffee action to people who use the coffee app every morning.", + "After people use a box office–type app to buy tickets to a movie, Siri might remind them to turn on Do Not Disturb shortly before showtime.", + "Siri might suggest an automation that starts a workout in a person’s favorite workout app and plays their favorite workout playlist as they enter their usual gym.", + "When people enter the airport after a home-bound flight, Siri might suggest they request a ride home from their favorite ride-sharing app." + ] + }, + { + "type": "paragraph", + "text": "When you provide information about your actions to the system, people can also use the Shortcuts app to create shortcuts for the system and custom intents you support. For guidance, see Shortcuts and suggestions." + } + ] + }, + { + "heading": "Design a great voice experience", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "A great voice interface helps people feel confident they’ll get the results they want, even when they’re not sure what they can say. Siri supports different voice experiences for system-provided intents and custom intents. With a system intent, Siri does the natural language processing for you, letting people interact with your app in various conversational ways. With a custom intent, your app helps people perform a task that Siri doesn’t know about yet, which results in a different type of support for the voice experience. Custom intents give you additional opportunities to customize conversational dialogue, but also require people to create and speak a precise phrase to start the interaction." + }, + { + "type": "paragraph", + "text": "As a designer, you have several ways to enhance both types of conversational experiences and help people specify what they want without engaging in lengthy exchanges." + }, + { + "type": "paragraph", + "text": "For system-provided intents, you help Siri communicate with people about the action they want to accomplish by providing essential information and defining any app-specific terminology that might come up during the conversation. You don’t have to write additional dialogue for Siri to speak because Siri already knows about the actions in the system-defined domains and understands many ways that people may talk about them. For example, if you need to confirm the recipient’s name during the resolve phase of a messaging intent, you simply indicate that the required parameter value is missing and Siri says to the sender “Who do you want to send it to?”" + }, + { + "type": "paragraph", + "text": "Even though you don’t write custom dialogue for system-provided intents, you can enhance the voice experience in other ways. For example, if people ask Siri to “play MyMusicApp” as they enter their gym, you could respond by playing their workout playlist." + }, + { + "type": "paragraph", + "text": "When you support a custom intent, people start the action by using their personal invocation phrase; if people don’t speak their phrase precisely, Siri doesn’t initiate the intent. Although you can suggest a memorable phrase for people to use, your principal job is to write clear, direct dialogue, often in the form of follow-up questions, to help people accomplish the action in as few steps as possible." + }, + { + "type": "paragraph", + "text": "For example, a coffee app might suggest Order coffee as a phrase people could use to reorder a favorite cup of coffee. In a scenario where people usually use Order coffee to order a cappuccino in various sizes, the coffee app could follow up with custom dialogue that builds on this knowledge, like “What size of cappuccino?” For other types of actions, more open-ended questions can be better at helping people accomplish the task efficiently. For example, if people start a grocery shopping action by saying Add to cart, the grocery shopping app could follow up with “OK, what do you want?”" + } + ] + }, + { + "heading": "Recognize that people use Siri in different contexts", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People can use Siri to get things done while they’re in a car, working out, using apps on a device, or interacting with HomePod. You don’t always know the context in which people are using Siri to perform your app’s actions, so flexibility is key to help people have a great experience no matter what they’re doing." + }, + { + "type": "paragraph", + "text": "To communicate with people regardless of their current context, supply information that Siri can provide both vocally and visually. Supporting both voice and screen-based content lets Siri decide which communication method works best for people in their current situation. For example, Siri speaks to people through their AirPods if they say “Hey Siri” while using them." + }, + { + "type": "paragraph", + "text": "In voice-only situations, Siri verbally describes information that would have been presented onscreen in other situations. Consider a food-delivery app that requires people to confirm a transaction before completing the order. In a voice-only scenario, Siri may say “Your total is fifteen dollars, and your order will take thirty minutes to arrive at your door. Ready to order?” In contrast, when people can view the cost and delivery information onscreen, Siri might simply say “Ready to order?” When you support custom intents, you’re responsible for supplying the voice-only dialogue that describes these types of onscreen information." + } + ] + }, + { + "heading": "System intents", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "SiriKit defines a large number of system intents that represent common tasks people do, such as playing music, sending messages to friends, and managing notes. For system intents, Siri defines the conversational flow, while your app provides the data to complete the interaction." + }, + { + "type": "paragraph", + "text": "SiriKit provides the following intents." + }, + { + "type": "table", + "rows": [ + [ + "Domain (link to developer guidance)", + "Intents" + ], + [ + "VoIP Calling", + "Initiate calls." + ], + [ + "Workouts", + "Start, pause, resume, end, and cancel workouts." + ], + [ + "Lists and Notes", + "Create notes." + ], + [ + "Search for notes." + ], + [ + "Create reminders based on a date, time, or location." + ], + [ + "Media", + "Search for and play media content, such as video, music, audiobooks, and podcasts." + ], + [ + "Like or dislike items." + ], + [ + "Add items to a library or playlist." + ], + [ + "Messaging", + "Send messages." + ], + [ + "Search for messages." + ], + [ + "Read received messages." + ], + [ + "Payments", + "Send payments." + ], + [ + "Request payments." + ], + [ + "Car Commands", + "Activate hazard lights or honk the horn." + ], + [ + "Lock and unlock the doors." + ], + [ + "Check the current fuel or power level." + ] + ] + } + ] + }, + { + "heading": "Design responses to system intents", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "People use Siri for convenience, and they expect a fast response. Your app needs to perform the system intents it supports quickly and accurately so that people have a great experience when they choose your app to get things done." + }, + { + "type": "paragraph", + "text": "Whenever possible, complete requests without leaving Siri. If a request must be finished in your app, take people directly to the expected destination. Don’t show intermediary screens or messages that slow down the experience." + }, + { + "type": "paragraph", + "text": "When a request has a financial impact, default to the safest and least expensive option. Never deceive people or misrepresent information. For a purchase with multiple pricing levels, don’t default to the most expensive. When people make a payment, don’t charge extra fees without informing them." + }, + { + "type": "paragraph", + "text": "When people request media playback from your app, consider providing alternative results if the request is ambiguous. When you display alternative results within the Siri UI, people can easily choose a different piece of content if your first offering isn’t what they want." + }, + { + "type": "paragraph", + "text": "On Apple Watch, design a streamlined workflow that requires minimal interaction. Whenever possible, use intelligent defaults instead of asking for input. For example, a music app could respond to a nonspecific request — like “Play music with MyMusicApp” — by playing a favorite playlist. If you must present options to people, offer a small number of relevant choices that reduce the need for additional prompting." + } + ] + }, + { + "heading": "Enhance the voice experience for system intents", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Help people learn how to use Siri to get things done in your app, and make conversation with Siri feel natural in the context of your brand, by defining app-specific terms and alternative ways people might refer to your app." + }, + { + "type": "paragraph", + "text": "Create example requests. When people tap the Help button in the Siri interface, they view a guide that can include example phrases that you supply. Write phrases that demonstrate the easiest and most efficient ways to use Siri with your app. For developer guidance, see Intent Phrases." + }, + { + "type": "paragraph", + "text": "Define custom vocabulary that people use with your app. Help Siri learn more about the actions your app performs by defining specific terms people might actually use in requests, like account names, contact names, photo tags, photo album names, ride options, and workout names. Make sure these terms are nongeneric and unique to your app. Never include other app names, terms that are obviously connected with other apps, inappropriate language, or reserved phrases, like Hey Siri. Note that Siri uses the terms you define to help resolve requests, but there’s no guarantee that Siri will recognize them." + }, + { + "type": "paragraph", + "text": "Consider defining alternative app names. If people might refer to your app in different ways, it’s a good idea to provide a list of alternative names to help Siri understand what people mean. For example, a UnicornChat app might define the term Unicorn as an alternative app name. Never impersonate other apps by listing their names as alternative names for your app." + } + ] + }, + { + "heading": "Design a custom interface for a system intent", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If it makes sense in your iOS app, you can supply custom interface elements or a completely custom UI for Siri or Maps to display along with your intent response. A watchOS app can’t provide a custom UI for Siri to display on Apple Watch." + }, + { + "type": "paragraph", + "text": "Avoid including extraneous or redundant information. A custom interface lets you bring elements from your app into the Siri interface, but displaying information that isn’t related to the action can distract people. You also want to avoid duplicating information that the system can display in the Siri or Maps interface. For developer guidance, see INParameter." + }, + { + "type": "paragraph", + "text": "Make sure people can still perform the action without viewing your custom interface. People can switch to voice-only interaction with Siri at any time, so it’s crucial to help Siri speak the same information that you display in your custom interface." + }, + { + "type": "paragraph", + "text": "Use ample margins and padding in your custom interface. Avoid extending content to the edges of your interface unless it’s content that appears to flow naturally offscreen, like a map. In general, provide a margin of 20 points between each edge of your interface and the content. Use the app icon that appears above your interface to guide alignment: content tends to look best when it’s lined up with the center of this icon." + }, + { + "type": "paragraph", + "text": "Minimize the height of your interface. The system displays other elements above and below your custom interface, such as the text prompt, the spoken response, and the Siri waveform. Aim for a custom interface height that’s no taller than half the height of the screen, so people can see all your content without scrolling." + }, + { + "type": "paragraph", + "text": "Refrain from displaying your app name or icon. The system automatically shows this information, so it’s redundant to include it in your custom interface." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Creating an Intents UI Extension." + } + ] + }, + { + "heading": "Custom intents", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "If your app lets people perform an everyday task that doesn’t fit into any of the SiriKit domains, you can create a custom intent to represent it (see System intents for a list of domains). You can also use a custom or system intent to support a shortcut, which gives people a quick way to initiate frequently performed actions by speaking a simple phrase or accepting a suggestion from Siri. To learn how to integrate your intents with the system so that people can discover them and add them to Siri, see Shortcuts and suggestions." + } + ] + }, + { + "heading": "Custom intent categories and responses", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Although your custom intent won’t belong to a SiriKit domain, you’ll need to model it on a system-defined intent category that’s related to your action. SiriKit defines several categories that represent generic tasks, like create, order, share, and search. Because these definitions are in the system, Siri knows how to communicate with people about common actions that are associated with each category — like placing an order or sharing content — in ways that feel natural." + }, + { + "type": "paragraph", + "text": "It’s important to choose the category that best represents your action because the category influences the ways Siri speaks about it and the controls people might see in the interface. For example, a coffee app would likely choose the order category to represent its custom order coffee intent, and as a result, Siri can speak default responses that make sense in the context of this action, like “Ready to order?” and “OK. Ordering.” Category choice can have other effects, too: Because the order category includes actions that have financial impact, using this category for the order coffee intent means that people will be asked to authenticate before completing the action." + }, + { + "type": "paragraph", + "text": "For several categories, the system defines additional verbs that are related to the category’s default action. You can use these alternative verbs to help ensure that the Siri dialogue and the button titles displayed in the interface align with the way you present your app’s actions. For example, in addition to the default verb order, the order category includes the verbs buy and book." + }, + { + "type": "paragraph", + "text": "SiriKit defines the following custom intent categories and associated verbs." + }, + { + "type": "table", + "rows": [ + [ + "Category", + "Default verb", + "Additional verbs" + ], + [ + "Generic", + "Do", + "Run, go" + ], + [ + "Information", + "View", + "Open" + ], + [ + "Order", + "Order", + "Book, buy" + ], + [ + "Start", + "Start", + "Navigate" + ], + [ + "Share", + "Share", + "Post, send" + ], + [ + "Create", + "Create", + "Add" + ], + [ + "Search", + "Search", + "Find, filter" + ], + [ + "Download", + "Download", + "Get" + ], + [ + "Other", + "Set", + "Request, toggle, check in" + ] + ] + }, + { + "type": "paragraph", + "text": "SiriKit also defines three response types:" + }, + { + "type": "list", + "items": [ + "Confirmation. Confirms that people still want to perform the action.", + "Success. Indicates that the action has been initiated.", + "Error. Tells people that the action can’t be completed." + ] + }, + { + "type": "paragraph", + "text": "In several custom intent categories, SiriKit defines default dialogue for each response type. For example, the default confirmation dialogue for the order category is, “Ready to order?” and the default success dialogue for the share category is, “OK. Shared.”" + }, + { + "type": "paragraph", + "text": "To customize a response, you create a template that combines dialogue you write with placeholders for relevant information your app can supply while it’s working on the intent. For example, a coffee app might enhance the default order confirmation dialogue by providing custom content that includes a placeholder for the total cost of the order." + }, + { + "type": "paragraph", + "text": "Depending on the response type, your custom dialogue is presented before or after the default dialogue. For example, confirmation responses present the default dialogue after any custom dialogue. In the coffee app example, the customized confirmation dialogue would begin with something like, “Your large coffee with cream comes to $2.50” and end with the default dialogue, “Ready to order?”" + } + ] + }, + { + "heading": "Design a custom intent", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "If a built-in SiriKit intent represents your action’s purpose, adopt that intent instead of defining a custom intent. For example, if you’d like to offer a shortcut for sending a message, adopt INSendMessageIntent; if you’d like to offer a shortcut for playing media, adopt INPlayMediaIntent. For guidance, see System intents." + }, + { + "type": "paragraph", + "text": "If your app’s action requires a custom intent, pick the category that most closely matches the action. A category informs the system about the general function of an intent or shortcut — like order, download, or search — and affects the text and spoken dialogue presented to people when a shortcut is offered by the system or used with Siri. You design the flow of conversation for the custom intents you offer, so it’s essential that you choose a category that corresponds to the meaning of each intent." + }, + { + "type": "tip", + "text": "TipIf your action’s primary purpose is to retrieve information or show something to people — like displaying a sports score or the weather — use the information category. Using a different category requires people to make additional taps to get the information." + }, + { + "type": "paragraph", + "text": "Design custom intents that accelerate common, useful tasks. Take advantage of the familiarity people have with your app, and make it easier for them to initiate the tasks they perform most often." + }, + { + "type": "paragraph", + "text": "Ensure that your intent works well in every scenario. Make it easy for people to run your intent as a shortcut, regardless of how they initiate it. For example, be prepared for people to run it using their voice on devices with and without a screen, from suggestions on the lock screen or the Siri face on Apple Watch, from search, and within a multistep shortcut." + }, + { + "type": "paragraph", + "text": "In general, design custom intents for tasks that aren’t overly complex. People benefit the most from intents that reduce the number of actions required to complete a task. Don’t counteract that simplicity by requiring people to engage in a lengthy conversation with your app. You can also reduce the likelihood of user errors by limiting custom intents to clearly defined tasks." + }, + { + "type": "paragraph", + "text": "Design your intents to be long-lived. Avoid offering intents that are date-specific or associated with temporary data. For example, it’s not a good idea for a travel app to offer a custom intent for each specific itinerary. A better intent might use follow-up questions to let people get the itinerary for one of their upcoming trips." + }, + { + "type": "paragraph", + "text": "Don’t request permission to use Siri. If your app supports only custom intents — and not system intents — you don’t need to get permission to use Siri before letting people create and use voice shortcuts for your intents. Asking for permission can slow people down and could discourage them from using your app’s custom intents." + }, + { + "type": "paragraph", + "text": "Support background operation. The best intents support shortcuts that run quickly and don’t pull people out of their current context. Strive to support custom intents that can run in the background without bringing your app to the front. Supporting background operation also ensures that people can complete the task in hands-free and voice-only scenarios." + } + ] + }, + { + "heading": "Help people customize their requests", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Custom intents can offer follow-up questions that let people do more with a single intent by refining its results on the fly. For example, if you offer an order coffee intent, you can help people get exactly what they want by asking them questions like, “What size?”, “What flavor?”, and “Which location?” Details like size, flavor, and location are parameters your app can define to help people personalize their request." + }, + { + "type": "paragraph", + "text": "People supply parameter values to personalize an intent by responding to your follow-up questions or by editing existing values in the Shortcuts app. For example, if you offer an order ground coffee intent that includes a parameter for the grind size, you might supply a follow-up question like, “Which grind?” For people who typically order the coarse grind, you could simplify the interaction by using the value coarse as the default parameter value in a dialogue like, “Do you want coarse-ground coffee?” If people choose a different grind, you can follow up by presenting the full list of options. In voice-only scenarios, Siri speaks your follow-up questions and sends you the responses. When people use the Shortcuts app to edit a parameter value, you receive the new value when they use the associated shortcut. For developer guidance, see Adding User Interactivity with Siri Shortcuts and the Shortcuts App." + }, + { + "type": "paragraph", + "text": "Design intents that require as few follow-up questions as possible. Often, an intent can fulfill a request without asking any follow-up questions. Although follow-up questions make intents more flexible, you don’t want to force people into a long interaction. In most cases, it’s best to offer just one or two follow-up questions." + }, + { + "type": "paragraph", + "text": "List the smallest number of options possible, and sort the items in a way that makes sense. As with too many follow-up questions, giving people too many options can make completing the task feel onerous. As you determine whether to include an item, consider its complexity as well as its utility. In a food-ordering app, for example, it might be easier for people to parse a list of individual menu items than a list of orders, each of which contains multiple items. After you identify a small number of useful items, consider sorting them by recency, frequency, or popularity." + }, + { + "type": "paragraph", + "text": "Make sure each follow-up question is meaningful. Ideally, each follow-up question helps people make an important choice. If options or questions you present are too granular or too similar, the conversation can become repetitive, and people may feel like using your intent is too much work." + }, + { + "type": "paragraph", + "text": "Design parameters that are easy for people to understand and use. Aim for parameters that represent simple values or attributes and name them using simple, straightforward terms. For example, a soup-ordering app might define parameters for the type of soup, the serving size, and a delivery location, using names like soup, size, and location. For guidance, see Shortcuts and suggestions." + }, + { + "type": "paragraph", + "text": "Ask for confirmation only when necessary. An intent can ask people for confirmation before completing the task or when interpreting an answer to a follow-up question. Apps that support tasks that have financial impact, like an app that helps people place orders, must ask for confirmation before completing an order. For tasks that don’t have financial impact, asking for confirmation can feel like too much extra work and can sometimes discourage people from completing their request. In all cases, avoid asking for confirmation more than once." + }, + { + "type": "paragraph", + "text": "Support follow-up questions when it makes sense. For example, an app that helps people order food might offer options for pickup or delivery, but ask for a specific location only after people choose the delivery option." + }, + { + "type": "paragraph", + "text": "Prioritize the options you offer based on the context in which people run your shortcut. For example, if people use your shortcut to order an item for pickup, offer pickup locations that are currently close by. Offering options that adapt to the context in which your shortcut is run can help people avoid creating separate shortcuts for specific options." + }, + { + "type": "paragraph", + "text": "Consider adjusting the parameter values you offer when people set up your shortcut. When you indicate that a parameter has dynamic options, you can enhance the shortcut setup experience in two ways:" + }, + { + "type": "list", + "items": [ + "You can find and present parameter values that are relevant to the context people are in while they’re setting up the shortcut. For example, if people use the Shortcuts app to choose a value for a store-location parameter, the parameter can dynamically generate a list of stores that are currently closest to the device.", + "You can present a comprehensive list of parameter values. When people set up a shortcut, having an extensive list of parameter values can help them create the shortcut they want. In contrast, when people use a shortcut to accelerate an action, they generally prefer the convenience of having a shorter list of choices." + ] + }, + { + "type": "paragraph", + "text": "For developer guidance, see the storeLocation parameter in the intent definition file of the Soup Chef: Accelerating App Interactions with Shortcuts sample code project." + } + ] + }, + { + "heading": "Enhance the voice experience for custom intents", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Aim to create conversational interactions. You can customize what Siri says throughout the voice experience, including the handling of follow-up questions. Try writing a script and acting it out with another person to see how well your dialogue works in a face-to-face exchange. Experiencing custom dialogue in this way can help you find places where the interaction doesn’t feel natural." + }, + { + "type": "paragraph", + "text": "Help people understand errors and failures. The system provides some default error descriptions, but it’s best to enhance error responses so that they’re specific to the current situation. For example, if chicken noodle soup is sold out, a soup app can respond with a custom error like, “Sorry, we’re out of chicken noodle soup” instead of “Sorry, we can’t complete your order.”" + }, + { + "type": "paragraph", + "text": "Strive for engaging voice responses. Remember that people may perform your app’s tasks from their HomePod, using “Hey Siri” with their AirPods, or through CarPlay without looking at a screen. In these cases, the voice response needs to convey the same essential information that the visual elements display to ensure that people can get what they need no matter how they interact with Siri." + }, + { + "type": "paragraph", + "text": "Create voice responses that are concise, descriptive, and effective in voice-driven scenarios. As with a shortcut title, an effective custom spoken response clearly conveys what’s happening as the shortcut runs. If you ask follow-up questions, be sure to customize the default dialogue for clarity. For example, “Which soup?” is clearer than “Which one?”" + }, + { + "type": "paragraph", + "text": "Avoid unnecessary repetition. People tend to run voice shortcuts frequently, so they may hear the same prompt multiple times when answering follow-up questions or dealing with errors. Use the context of the current conversation to remove as many details from the prompts as possible. Avoid including unnecessary words or attempts at humor, because both can become irritating over time." + }, + { + "type": "paragraph", + "text": "Help conversations with Siri feel natural. People interact with Siri in a variety of ways, like choosing a list item by saying “the second one,” or, in the case of a soup-ordering app, saying “large” or “small” instead of “bowl” or “cup.” You can make people’s Siri interactions feel more natural when you give the system alternative terms and phrases that work as app-specific synonyms (like using “bowl” as a synonym for “large”). Also consider enhancing clarity by providing alternative dialogue options for Siri to speak. For example, the soup app might present a list of onscreen menu options like “1 clam chowder,” or “1 clam chowder and 1 tomato,” but speak these options as “Which order? The one with clam chowder only or the one that includes tomato?”" + }, + { + "type": "paragraph", + "text": "Exclude your app name. The system provides verbal and visual attribution for your app when responding to people. Including your appʼs name in a verbal response is redundant and may make the experience of interacting with Siri feel less natural. Siri speaks your app’s name less frequently when people have used a shortcut several times, because it isn’t necessary to keep reminding them which app is responding." + }, + { + "type": "paragraph", + "text": "Don’t attempt to mimic or manipulate Siri. Never impersonate Siri, attempt to reproduce the functionality that Siri provides, or provide a response that appears to come from Apple." + }, + { + "type": "paragraph", + "text": "Be appropriate and respect parental controls. Never present offensive or demeaning content. Keep in mind that many families use parental controls to restrict explicit content and content that’s based on specific rating levels." + }, + { + "type": "paragraph", + "text": "Avoid using personal pronouns. Create content that’s inclusive of all people." + }, + { + "type": "paragraph", + "text": "Consider letting people view more options in your app. If the list of options doesn’t include the items people need, you might want to include an item that lets people open your app to see more. In the list, you could use copy like, “See more in App Name,” and in spoken dialogue, you might encourage people to say, “More options.”" + }, + { + "type": "paragraph", + "text": "Keep responses device-independent. People may use Siri to interact with your app via Apple Watch, HomePod, iPad, iPhone, or CarPlay. If you must provide device-specific wording, make sure it accurately reflects the person’s current device." + }, + { + "type": "paragraph", + "text": "Don’t advertise. Don’t include advertisements, marketing, or in-app purchase sales pitches in your intent content." + } + ] + }, + { + "heading": "Shortcuts and suggestions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you support shortcuts, people have a variety of ways to discover and interact with the custom and system intents your app provides. For example:" + }, + { + "type": "list", + "items": [ + "Siri can suggest a shortcut for an action people have performed at least once by offering it in search results, on the lock screen, and in the Shortcuts app.", + "Your app can supply a shortcut for an action that people haven’t done yet but might want to do in the future, so that the Shortcuts app can suggest it or it can appear on the Siri watch face.", + "People can use the Shortcuts app to view all their shortcuts and even combine actions from different apps into multistep shortcuts.", + "People can also use the Shortcuts app to automate a shortcut by defining the conditions that can run it, like time of day or current location." + ] + }, + { + "type": "paragraph", + "text": "The Shortcuts app is also available in macOS 12 and later and in watchOS 7 and later. For developer guidance, see SiriKit." + }, + { + "type": "note", + "text": "Developer noteThe Add to Siri method for adding shortcuts is no longer supported. See App Shortcuts for ways to integrate your app with Siri and the system." + } + ] + }, + { + "heading": "Make app actions widely available", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Donating information about the actions your app supports helps the system offer them to people in various ways, such as:" + }, + { + "type": "list", + "items": [ + "In search results", + "Throughout the Shortcuts app", + "On the lock screen as a Siri Suggestion", + "Within the Now Playing view (for recently played media content)", + "During Wind Down" + ] + }, + { + "type": "paragraph", + "text": "Donations also power Automation Suggestions in the Shortcut app’s Gallery, making it easy for people to set up automations for hands-free interactions with your app." + }, + { + "type": "paragraph", + "text": "You can also tell the system about shortcuts for actions people haven’t taken yet or make a shortcut available on the Siri watch face (for guidance, see Suggest Shortcuts people might want to add to Siri and Display shortcuts on the Siri watch face). For developer guidance, see Donating Shortcuts." + }, + { + "type": "paragraph", + "text": "Make a donation every time people perform the action. When you donate a shortcut each time people perform the associated action, you help the system more accurately predict the best time and place to offer the shortcut." + }, + { + "type": "paragraph", + "text": "Only donate actions that people actually perform. For example, a coffee-ordering app donates the Order coffee shortcut every time people order coffee, but not when people do something else, like browse the menu. Similarly, a media app donates information about a song — like its title and album — only when people are actually listening to it. (For developer guidance, see Improving Siri Media Interactions and App Selection.)" + }, + { + "type": "paragraph", + "text": "Remove donations for actions that require corresponding data. If information required by a donated action no longer exists, your app needs to delete the donation so the shortcut isn’t suggested anymore. For example, if people delete a contact in a messaging app, the app needs to delete donations for messaging that contact. When people create a shortcut themselves, only they can delete it. For developer guidance, see Deleting Donated Shortcuts." + }, + { + "type": "paragraph", + "text": "If your app handles reservations, consider donating them to the system. These items — like ticketed events, travel itineraries, or reservations for restaurants, flights, or movies — automatically appear as suggestions in Calendar or Maps. When you donate a reservation, it can appear on the lock screen with a suggestion to check in with your app or as a reminder that uses current traffic conditions to recommend when people should leave. For developer guidance, see Donating Reservations." + } + ] + }, + { + "heading": "Suggest Shortcuts people might want to add to Siri", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "If your app supports an action that people haven’t performed yet but might find useful, you can provide a suggested shortcut to the system so that people can discover it. For example, if people use a coffee-ordering app to order their daily coffee but not to order a holiday special, the app might still want to give them a way to do this with an Order holiday coffee shortcut." + }, + { + "type": "paragraph", + "text": "Suggested shortcuts appear in both the Gallery and the shortcut editor in the Shortcuts app. For developer guidance, see Offering Actions in the Shortcuts App." + } + ] + }, + { + "heading": "Display shortcuts on the Siri watch face", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "On Apple Watch, people can run shortcuts in several ways. For example, people can ask Siri, tap a shortcut complication on a watch face, or use the Shortcuts app available in watchOS 7 and later. You can also make shortcuts available on the Siri watch face." + }, + { + "type": "paragraph", + "text": "To have a shortcut appear on the Siri watch face, you define a relevant shortcut by including information like the time of day at which your shortcut is relevant and how the shortcut can display on the Siri watch face. The information you supply lets the Siri watch face intelligently display your shortcut to people when they’re in the appropriate context." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Defining Relevant Shortcuts for the Siri Watch Face." + } + ] + }, + { + "heading": "Create shortcut titles and subtitles", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Shortcut titles and subtitles appear when the system suggests them. In Siri Suggestions on iPhone and Apple Watch, a shortcut can also display an image." + }, + { + "type": "paragraph", + "text": "Be concise but descriptive. An effective title conveys what happens when the shortcut runs. A subtitle can provide additional detail that supplements — but doesn’t duplicate — the title." + }, + { + "type": "paragraph", + "text": "Start titles with a verb and use sentence-style capitalization without punctuation. Think of a shortcut title as a brief instruction." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example title" + ], + [ + "", + "Order my favorite coffee" + ], + [ + "", + "Large latte" + ], + [ + "", + "Show today’s forecast" + ], + [ + "", + "Weather forecast" + ] + ] + }, + { + "type": "paragraph", + "text": "Lead with important information. Long titles and subtitles may be truncated in certain contexts, depending on the device’s screen size." + }, + { + "type": "paragraph", + "text": "Exclude your app name. The system already identifies the app associated with a shortcut." + }, + { + "type": "paragraph", + "text": "Localize titles and subtitles. Providing content in multiple languages ensures an equally great experience for people everywhere." + }, + { + "type": "paragraph", + "text": "Consider providing a custom image for a more engaging suggestion. For example, the shortcut for Order my favorite coffee could show a cup of the customer’s favorite coffee. Create an image that measures:" + }, + { + "type": "list", + "items": [ + "60x60 pt (180x180 px @ 3x) to display in an iOS app", + "34x34 pt (68x68 px @2x) to display on the Siri watch face on the 44mm Apple Watch (watchOS scales down the image for smaller watches)" + ] + } + ] + }, + { + "heading": "Provide default phrases for shortcuts", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Your app provides default phrases for shortcuts during setup. People can personalize these phrases when adding your shortcuts to Siri." + }, + { + "type": "paragraph", + "text": "Keep phrases short and memorable. Bear in mind that people must speak your phrase verbatim, so long or confusing phrases may result in mistakes and frustration. Two- and three-word phrases tend to work best. More words can be harder for people to remember, and phrases that are too long will get truncated." + }, + { + "type": "paragraph", + "text": "Make sure the phrases you suggest are accurate and specific. Phrases like Reorder coffee or Order my usual coffee clearly describe what the shortcut does, which makes it easier for people to remember the phrase later. Also make sure that your suggested phrases are specific to each shortcut’s scope. For example, Watch baseball is clearer and more memorable than Watch sports. It’s also important to avoid implying that people can vary a shortcut’s invocation phrase to get a different result. For example, people might interpret a phrase like Order a large clam chowder to mean that your shortcut will give them what they want if they substitute “small” for “large” and “lobster bisque” for “clam chowder.”" + }, + { + "type": "paragraph", + "text": "Don’t commandeer core Siri commands. For example, never suggest a phrase like Call 911 or include the text Hey Siri." + } + ] + }, + { + "heading": "Make shortcuts customizable", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When you define a parameter for each detail your app needs to perform an intent, people can customize the shortcut by editing these details in the Shortcuts app." + }, + { + "type": "paragraph", + "text": "To show people which details they can edit and how their edits affect the action, you provide a parameter summary. A parameter summary succinctly describes the action by using the parameters in a sentence that begins with a verb. For example, a customizable Order coffee shortcut could display a parameter summary like “Order quantity coffee” where quantity and coffee are the parameters that people can edit. Here’s an example of how the Order coffee shortcut might look after people supply values for the quantity and coffee parameters." + }, + { + "type": "paragraph", + "text": "Provide a parameter summary for each custom intent you support. At minimum, include in your parameter summary all parameters your intent requires and any parameters that receive values from other apps or actions. The summary doesn’t have to include optional parameters or parameters that people aren’t likely to edit; if you omit parameters like these from the summary, people can still access them in the Show More section." + }, + { + "type": "paragraph", + "text": "Craft a short parameter summary that’s clearly related to your intent’s title. When the intent title and the parameter summary are similar, it’s easy for people to recognize the action regardless of where they view it. Aim to use the same words in the summary and the title — in particular, it’s helpful to begin both phrases with the same verb. For example, if your intent title is “Search encyclopedia,” a good parameter summary could be “Search encyclopedia for search term.”" + }, + { + "type": "paragraph", + "text": "Aim for a parameter summary that reads like a sentence. Use sentence-style capitalization, but don’t include ending punctuation. When possible, avoid punctuation entirely. Punctuation within a summary — especially colons, semicolons, and parentheses — can make the summary hard to read and understand." + }, + { + "type": "paragraph", + "text": "Provide multiple parameter summaries when necessary. If your action includes a parameter that has a parent-child relationship with other parameters, you can provide multiple variants of the summary based on the current value of the parent parameter. For example, if your order coffee shortcut lets people specify whether they want to pick up their order or have it delivered, your parameter summary can reflect the current choice. In this scenario, create one parameter summary that helps people pick a store location and another summary that helps them pick a delivery address. Be sure to use a consistent grammatical structure and parameter order in all variants of the summary that you create." + }, + { + "type": "paragraph", + "text": "Provide output parameters for information that people can use in a multistep shortcut. For example, an order coffee action might provide output that includes the estimated delivery time and the cost of the order. With this information, people could create a multistep shortcut that messages a friend about the delivery time and logs the transaction in their favorite budgeting app." + }, + { + "type": "paragraph", + "text": "Consider defining an input parameter. When you define an input parameter for an action, the action can automatically receive output from a preceding action in a multistep shortcut. For example, if your action applies a filter to the image it receives in an image parameter, you might designate image as the input parameter so that it automatically accepts images from other actions. You configure an input parameter in your intent definition file (shown in Adding User Interactivity with Siri Shortcuts and the Shortcuts App)." + }, + { + "type": "paragraph", + "text": "Help people distinguish among different variations of the same action. For example, an app that offers a send message action might use a contact photo to help people visually distinguish the various messages they send. To do this, choose the parameter that’s most identifiable to people and designate it as the key parameter (shown in Adding User Interactivity with Siri Shortcuts and the Shortcuts App). Be sure to provide an image for the key parameter every time you donate the action (for developer guidance, see INImage)." + }, + { + "type": "paragraph", + "text": "Avoid providing multiple actions that perform the same basic task. For example, instead of providing an action that adds text to a note and a different action that adds an image, consider providing a single action that lets people add both types of content. Providing a few high-level actions can make it easier for people to understand what the actions do when they’re combined in a multistep shortcut." + }, + { + "type": "paragraph", + "text": "For developer guidance, see Shortcut-Related UI." + } + ] + }, + { + "heading": "Editorial guidelines", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Don’t refer to Siri using pronouns like “she,” “him,” or “her.” Ideally, just use the word Siri. For example, After you add a shortcut to Siri, you can run the shortcut anytime by asking Siri." + }, + { + "type": "paragraph", + "text": "Use correct capitalization and punctuation when using the term Hey Siri. Hey Siri is two words, italicized or in quotes, with an uppercase H and uppercase S. Do not follow the term with an ellipsis." + }, + { + "type": "table", + "rows": [ + [ + "", + "Example text" + ], + [ + "", + "Say Hey Siri to activate Siri." + ], + [ + "", + "Say “Hey Siri” to activate Siri." + ], + [ + "", + "Say Hey Siri… to activate Siri." + ], + [ + "", + "Say “hey Siri” to activate Siri." + ] + ] + }, + { + "type": "paragraph", + "text": "In a localized context, translate only the word Hey in the phrase Hey Siri. As an Apple trademark, Siri is never translated. Here is a list of acceptable translations for the phrase Hey Siri:" + }, + { + "type": "table", + "rows": [ + [ + "Locale code", + "Hey Siri translation", + "Locale code", + "Hey Siri translation" + ], + [ + "ar_AE", + "يا Siri", + "fr_CA", + "Dis Siri" + ], + [ + "ar_SA", + "يا Siri", + "fr_CH", + "Dis Siri" + ], + [ + "da_DK", + "Hej Siri", + "fr_FR", + "Dis Siri" + ], + [ + "de_AT", + "Hey Siri", + "it_CH", + "Ehi Siri" + ], + [ + "de_CH", + "Hey Siri", + "it_IT", + "Ehi Siri" + ], + [ + "de_DE", + "Hey Siri", + "ja_JP", + "Hey Siri" + ], + [ + "en_AU", + "Hey Siri", + "ko_KR", + "Siri야" + ], + [ + "en_CA", + "Hey Siri", + "ms_MY", + "Hai Siri" + ], + [ + "en_GB", + "Hey Siri", + "nb_NO", + "Hei Siri" + ], + [ + "en_IE", + "Hey Siri", + "nl_BE", + "Hé, Siri" + ], + [ + "en_IN", + "Hey Siri", + "nl_NL", + "Hé Siri" + ], + [ + "en_NZ", + "Hey Siri", + "no_NO", + "Hei Siri" + ], + [ + "en_SG", + "Hey Siri", + "pt_BR", + "E aí Siri" + ], + [ + "en_US", + "Hey Siri", + "ru_RU", + "привет Siri" + ], + [ + "en_ZA", + "Hey Siri", + "sv_SE", + "Hej Siri" + ], + [ + "es_CL", + "Oye Siri", + "th_TH", + "หวัดดี Siri" + ], + [ + "es_ES", + "Oye Siri", + "tr_TR", + "Hey Siri" + ], + [ + "es_MX", + "Oye Siri", + "zh_CN", + "嘿Siri" + ], + [ + "es_US", + "Oye Siri", + "zh_HK", + "喂 Siri" + ], + [ + "fi_FI", + "Hei Siri", + "zh_TW", + "嘿 Siri" + ], + [ + "fr_BE", + "Dis Siri", + "", + "" + ] + ] + } + ] + }, + { + "heading": "Referring to Shortcuts", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "When referring to the Shortcuts feature or app, always typeset with a capital S and make sure that Shortcuts is plural. For example, MyApp integrates with Shortcuts to provide a quick way to get things with just a tap or by asking Siri." + }, + { + "type": "paragraph", + "text": "When referring to individual shortcuts (that is, not the feature or the Shortcuts app), use lowercase. For example, Run a shortcut by asking Siri or tapping a suggestion on the Lock Screen." + }, + { + "type": "paragraph", + "text": "Use the right terminology when describing how people can use Shortcuts in your app. People run shortcuts by asking Siri, so your wording needs to be very similar to phrases like Run a shortcut by asking Siri or Run the shortcut by asking Siri with your personalized phrase (localized as appropriate). Avoid using phrases like add voice shortcuts, make a voice command, create a voice prompt, or any other variation. Instead, consider a phrase like Add a shortcut to Siri to run with your voice (localized as appropriate)." + }, + { + "type": "paragraph", + "text": "To encourage people to create or use shortcuts in ways other than voice — like automations, Home Screen shortcuts, and other methods — use a phrase that doesn’t specify a particular method, like For quick access, add to Shortcuts." + }, + { + "type": "note", + "text": "NoteUse translations of your app name and the word Shortcuts — but not Siri — when referring to them in a localized context." + } + ] + }, + { + "heading": "Referring to Apple products", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Adhere to Apple’s trademark guidelines. Apple trademarks can’t appear in your app name or images. In text, use Apple product names exactly as shown on the Apple Trademark List." + }, + { + "type": "list", + "items": [ + "Use Apple product names in singular form only; don’t make Apple product names possessive.", + "Don’t translate Apple, Siri, or any other Apple trademark.", + "Don’t use category descriptors. For example, say iPad, not tablet.", + "Don’t indicate any kind of sponsorship, partnership, or endorsement from Apple.", + "Attribute Apple, Siri, and all other Apple trademarks with the correct credit lines wherever legal information appears within your app.", + "Refer to Apple devices and operating systems only in technical specifications or compatibility descriptions." + ] + }, + { + "type": "paragraph", + "text": "See 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": "App Shortcuts" + }, + { + "type": "paragraph", + "text": "Design for intelligence" + }, + { + "type": "paragraph", + "text": "Guidelines for using Apple trademarks and copyrights" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "SiriKit" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 5, 2023", + "Removed Add to Siri guidance. Added references to the new App Shortcuts page." + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "HomeKit", + "url": "/design/human-interface-guidelines/homekit" + }, + { + "title": "AirPlay", + "url": "/design/human-interface-guidelines/airplay" + }, + { + "title": "Integrating your app with Siri", + "url": "/design/human-interface-guidelines/siri#Integrating-your-app-with-Siri" + }, + { + "title": "System intents", + "url": "/design/human-interface-guidelines/siri#System-intents" + }, + { + "title": "Custom intents", + "url": "/design/human-interface-guidelines/siri#Custom-intents" + }, + { + "title": "A closer look at intents", + "url": "/design/human-interface-guidelines/siri#A-closer-look-at-intents" + }, + { + "title": "Provide information about actions and support suggestions", + "url": "/design/human-interface-guidelines/siri#Provide-information-about-actions-and-support-suggestions" + }, + { + "title": "Shortcuts and suggestions", + "url": "/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" + }, + { + "title": "Design a great voice experience", + "url": "/design/human-interface-guidelines/siri#Design-a-great-voice-experience" + }, + { + "title": "Recognize that people use Siri in different contexts", + "url": "/design/human-interface-guidelines/siri#Recognize-that-people-use-Siri-in-different-contexts" + }, + { + "title": "Design responses to system intents", + "url": "/design/human-interface-guidelines/siri#Design-responses-to-system-intents" + }, + { + "title": "Enhance the voice experience for system intents", + "url": "/design/human-interface-guidelines/siri#Enhance-the-voice-experience-for-system-intents" + }, + { + "title": "Design a custom interface for a system intent", + "url": "/design/human-interface-guidelines/siri#Design-a-custom-interface-for-a-system-intent" + }, + { + "title": "Custom intent categories and responses", + "url": "/design/human-interface-guidelines/siri#Custom-intent-categories-and-responses" + }, + { + "title": "Design a custom intent", + "url": "/design/human-interface-guidelines/siri#Design-a-custom-intent" + }, + { + "title": "Help people customize their requests", + "url": "/design/human-interface-guidelines/siri#Help-people-customize-their-requests" + }, + { + "title": "Enhance the voice experience for custom intents", + "url": "/design/human-interface-guidelines/siri#Enhance-the-voice-experience-for-custom-intents" + }, + { + "title": "App Shortcuts", + "url": "/design/human-interface-guidelines/app-shortcuts" + }, + { + "title": "Make app actions widely available", + "url": "/design/human-interface-guidelines/siri#Make-app-actions-widely-available" + }, + { + "title": "Suggest Shortcuts people might want to add to Siri", + "url": "/design/human-interface-guidelines/siri#Suggest-Shortcuts-people-might-want-to-add-to-Siri" + }, + { + "title": "Display shortcuts on the Siri watch face", + "url": "/design/human-interface-guidelines/siri#Display-shortcuts-on-the-Siri-watch-face" + }, + { + "title": "complication", + "url": "/design/human-interface-guidelines/complications" + }, + { + "title": "Create shortcut titles and subtitles", + "url": "/design/human-interface-guidelines/siri#Create-shortcut-titles-and-subtitles" + }, + { + "title": "Provide default phrases for shortcuts", + "url": "/design/human-interface-guidelines/siri#Provide-default-phrases-for-shortcuts" + }, + { + "title": "Make shortcuts customizable", + "url": "/design/human-interface-guidelines/siri#Make-shortcuts-customizable" + }, + { + "title": "Editorial guidelines", + "url": "/design/human-interface-guidelines/siri#Editorial-guidelines" + }, + { + "title": "Referring to Shortcuts", + "url": "/design/human-interface-guidelines/siri#Referring-to-Shortcuts" + }, + { + "title": "Referring to Apple products", + "url": "/design/human-interface-guidelines/siri#Referring-to-Apple-products" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/siri#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/siri#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/siri#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/siri#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/siri#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/siri#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Tap to Pay on iPhone", + "url": "https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you support Tap to Pay on iPhone in your iOS payment app, you help merchants present a consistent and trusted payment experience to their customers." + }, + { + "type": "note", + "text": "NoteTap to Pay on iPhone works alongside your existing payment-acceptance hardware and accessories." + }, + { + "type": "paragraph", + "text": "Before you can integrate Tap to Pay on iPhone into your iOS app, you need to work with a supported payment service provider (PSP), request the Tap to Pay on iPhone entitlement, and use ProximityReader APIs, either through the PSP’s SDK or by adopting the framework. For high-level guidance — including marketing recommendations for letting people know about your app’s new capabilities — see Tap to Pay on iPhone; for developer guidance, see Setting up Tap to Pay on iPhone." + }, + { + "type": "note", + "text": "NoteIf your PSP offers an SDK that supplies user interfaces for experiences like showing a tap result, see the documentation the PSP provides." + } + ] + }, + { + "heading": "Enabling Tap to Pay on iPhone", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Before your app can enable Tap to Pay on iPhone and configure a merchant’s device, the merchant must accept the relevant terms and conditions. Use the ProximityReader API to help you get the current status and present an acceptance flow only when necessary. For developer guidance, see Adding support for Tap to Pay on iPhone to your app." + }, + { + "type": "paragraph", + "text": "Help merchants accept Tap to Pay on iPhone terms and conditions before they begin interacting with their customers. Merchants must accept the terms and conditions before you perform the initial device configuration, so it works well when they can do so before they begin a checkout or other customer-facing flow. For example, you can provide buttons that let people accept Tap to Pay on iPhone terms and conditions from within your in-app messaging or onboarding flows." + }, + { + "type": "paragraph", + "text": "An app screen that offers a way to accept Tap to Pay on iPhone terms and conditions" + }, + { + "type": "paragraph", + "text": "An app screen that shows Tap to Pay on iPhone is enabled and offers a way to try it" + }, + { + "type": "paragraph", + "text": "Present Tap to Pay on iPhone terms and conditions only to an administrative user. If a nonadministrator tries to activate the feature, present a message explaining that administrator access is required. If your app’s primary users are enterprise or nonadministrative users, you can let an administrator accept Tap to Pay on iPhone terms and conditions through a web interface or a different app, including one that can run on devices other than iPhone. Contact your PSP for implementation details." + }, + { + "type": "paragraph", + "text": "If necessary, help merchants make sure their device is up to date. If your PSP requires specific versions of iOS, be sure to present the terms and conditions only after the merchant updates their device." + } + ] + }, + { + "heading": "Educating merchants", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Some merchants may be unfamiliar with Tap to Pay on iPhone, so it’s important to give them a quick and easy way to get started." + }, + { + "type": "paragraph", + "text": "Provide a tutorial that describes the supported payment types and shows how to use Tap to Pay on iPhone to accept each type. You can offer this tutorial by:" + }, + { + "type": "list", + "items": [ + "Including it in a Learn More option in your in-app messaging", + "Automatically presenting it after merchants accept the Tap to Pay on iPhone terms and conditions", + "Automatically presenting it to new users of your app", + "Making it easy to find in a consistent place like your app’s help content or settings area" + ] + }, + { + "type": "paragraph", + "text": "You can build your app’s tutorial using Apple-approved assets from the Tap to Pay on iPhone marketing guidelines, or you can use the ProximityReaderDiscovery API to provide a pre-built merchant education experience. Apple ensures that the API is up to date and is localized for the merchant’s region." + }, + { + "type": "paragraph", + "text": "Your app’s settings area is a good place to make sure the tutorial is always available." + }, + { + "type": "paragraph", + "text": "The merchant education tutorial provided by the ProximityReaderDiscovery API." + }, + { + "type": "paragraph", + "text": "If you design your own tutorial, make sure it shows how to:" + }, + { + "type": "list", + "items": [ + "Launch a checkout flow for each type of payment", + "Help a customer position their contactless card or digital wallet on the merchant’s device for payment", + "Handle PIN entry for a card, including accessibility mode" + ] + }, + { + "type": "paragraph", + "text": "Finally, provide an opportunity at the end of the tutorial for merchants who haven’t accepted the Tap to Pay on iPhone terms and conditions yet to do so." + } + ] + }, + { + "heading": "Checking out", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Checking out is a time-sensitive action, and merchants need the process to work smoothly. As you design your checkout flow, be prepared to:" + }, + { + "type": "list", + "items": [ + "Offer payment options in addition to Tap to Pay on iPhone, as necessary", + "Respond quickly if a merchant initiates checkout before enabling Tap to Pay on iPhone", + "Help merchants perform checkout even if device configuration is still in progress", + "Present pre-payment actions that affect the final total before checkout completes" + ] + }, + { + "type": "paragraph", + "text": "Provide Tap to Pay on iPhone as a checkout option whether the feature is enabled or not. Including a Tap to Pay on iPhone button gives merchants the flexibility to use the feature without exiting the checkout flow. When merchants tap the button, present the terms and conditions if necessary and automatically display the Tap to Pay on iPhone screen when configuration completes." + }, + { + "type": "paragraph", + "text": "Avoid making merchants wait to use Tap to Pay on iPhone. In addition to performing the initial configuration for each device, you need to perform a subsequent configuration each time your app becomes frontmost. To minimize potential wait times, prepare the feature as soon as your app starts and immediately after each transition to the foreground. For developer guidance, see prepare(using:)." + }, + { + "type": "paragraph", + "text": "Make sure the Tap to Pay on iPhone checkout option is available even if configuration is continuing in the background. Merchants must always be able to select the Tap to Pay on iPhone checkout option in a checkout flow. During configuration, let merchants select the checkout option and then display a progress indicator — avoid waiting for configuration to complete before making the option available. In most scenarios, you can display an indeterminate progress indicator, but if ProximityReader API shows that configuration is ongoing, display a determinate progress indicator. For guidance, see Progress indicators; for developer guidance see PaymentCardReader.Event.updateProgress(_:)." + }, + { + "type": "paragraph", + "text": "An app screen that displays a determinate progress indicator during configuration" + }, + { + "type": "paragraph", + "text": "An app screen that displays an indeterminate progress indicator during configuration" + }, + { + "type": "paragraph", + "text": "If your app supports multiple payment-acceptance methods, make the Tap to Pay on iPhone button easy to find. Avoid making merchants scroll to access the feature. If your app doesn’t support other payment acceptance options, open Tap to Pay on iPhone automatically when checkout begins." + }, + { + "type": "paragraph", + "text": "Make it easy for merchants to switch between Tap to Pay on iPhone and the hardware accessories you support. Even though your support for Tap to Pay on iPhone is separate from your support for a hardware accessory, such as a Bluetooth chip and PIN card reader, you can streamline the user experience by helping merchants set up both methods at the same time. After setup, make sure merchants can choose the appropriate payment-acceptance method during the checkout flow without having to visit your app settings." + }, + { + "type": "paragraph", + "text": "For the label of the button that activates the feature, use “Tap to Pay on iPhone” or, if space is constrained, “Tap to Pay.” The exception is if Tap to Pay on iPhone is the only payment-acceptance method you support. In this case, you can reuse your existing Charge or Checkout buttons to activate Tap to Pay on iPhone. If you support multiple payment-acceptance methods and you use icons in the buttons that activate them, use the wave.3.right.circle or wave.3.right.circle.fill SF Symbols in your Tap to Pay on iPhone button. Always avoid including the Apple logo in Tap to Pay on iPhone buttons." + }, + { + "type": "important", + "text": "ImportantUse the “Tap to Pay on iPhone” label only for payment actions. For language you can use for nonpayment actions, see Additional interactions." + }, + { + "type": "paragraph", + "text": "Design your Tap to Pay on iPhone button to match the other buttons in your app. Although you must use the labels “Tap to Pay on iPhone” or “Tap to Pay” as described above, you can use the button color and shape that coordinate best with your interface." + }, + { + "type": "paragraph", + "text": "Determine the final amount that customers need to pay before merchants initiate the Tap to Pay on iPhone experience. For example, if your app supports tipping or other customer interactions that can affect the total, make sure merchants offer these interactions before displaying the Tap to Pay on iPhone screen. Aim to display the final amount customers need to pay in the Tap to Pay on iPhone screen." + }, + { + "type": "paragraph", + "text": "If you support pre-payment options in your checkout flow, display them before the Tap to Pay on iPhone screen. For example, if you support the selection of different payment types, you can display these options in your checkout screen after a merchant taps the Tap to Pay on iPhone button and before you open the Tap to Pay on iPhone screen." + } + ] + }, + { + "heading": "Displaying results", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Customers pay by tapping — that is, bringing a contactless card or digital wallet near the Tap to Pay on iPhone screen in your app. After a successful tap (and after a successful PIN entry, if required), Tap to Pay on iPhone displays a checkmark and gives your app an object that contains the encrypted payment information you send to your PSP for processing. When a tap fails, Tap to Pay on iPhone displays an error screen. Your app is responsible for displaying transaction results after a successful tap or offering alternative payment options after an unsuccessful tap." + }, + { + "type": "paragraph", + "text": "Start processing a transaction as soon as possible. The system provides API you can use to request the result of a successful tap before the Tap to Pay on iPhone screen finishes displaying the checkmark animation that indicates tap completion. For developer guidance, see returnReadResultImmediately." + }, + { + "type": "paragraph", + "text": "Display a progress indicator while payment is authorizing before you show your transaction result screen. Transaction authorization can take several seconds to complete, depending on factors like connectivity for both the PSP and the merchant’s device. To ensure a smooth visual transition, display your authorization progress indicator after the Tap to Pay on iPhone screen animation finishes (for developer guidance, see PaymentCardReader.Event.readyForTap)." + }, + { + "type": "paragraph", + "text": "Clearly display the result of a transaction, whether it’s declined or successful. A transaction can be declined for reasons like insufficient funds, suspicion of fraud, or when the customer enters an incorrect PIN. As much as possible, also give the merchant ways to offer customers a digital receipt, such as through a QR code or text message." + }, + { + "type": "paragraph", + "text": "Help merchants complete the checkout flow when a payment can’t complete with Tap to Pay on iPhone. For example, a tap can fail when a card isn’t readable, isn’t from a supported payment network, doesn’t allow transactions at the stated amount, or doesn’t allow online PIN entry. In cases like these, you can:" + }, + { + "type": "list", + "items": [ + "Present a new screen or reuse your checkout screen, letting merchants accept an alternate form of payment, like cash", + "Support checkout with a different method, like external hardware or a payment link", + "Relaunch Tap to Pay on iPhone, if a customer has another card they want to try" + ] + }, + { + "type": "paragraph", + "text": "After you receive payment card data, you might also encounter scenarios like the ones listed below. If such scenarios occur, contact your PSP for guidance on addressing them." + }, + { + "type": "list", + "items": [ + "Some regions require Strong Customer Authentication (SCA) support, which means that although the payment card might not require a card PIN during a tap, the bank that issues the card can request a PIN after receiving the transaction processing request. In this scenario, your app may need to display the PIN entry screen instead of the transaction result.", + "In some regions your app may need to meet additional requirements to address the limitations of some cards, such as those in Offline PIN markets. Some PSPs support additional PIN fallback functionality to collect partial data from a tap, letting merchants continue the payment with another method such as a payment link." + ] + }, + { + "type": "paragraph", + "text": "If the system returns an error that the merchant must address, display a clear description of the problem and recommend an appropriate resolution. For example, if the device’s version of iOS doesn’t support Tap to Pay on iPhone, present an alert that recommends updating to the latest version. For developer guidance, see PaymentCardReaderSession.ReadError." + }, + { + "type": "paragraph", + "text": "Make it easy for merchants to get help with issues they can’t resolve. For example, direct merchants to the help content in your app or on your website, and provide an action that contacts your support team." + } + ] + }, + { + "heading": "Additional interactions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Tap to Pay on iPhone lets merchants read a payment card when there’s no transaction amount to support use cases like looking up a past transaction, or retaining card information to ensure future payment, issue refunds, or verify customer information." + }, + { + "type": "paragraph", + "text": "Use a generic label in a button that opens the Tap to Pay on iPhone screen to read a payment card when there’s no transaction amount. Don’t include “Tap to Pay on iPhone” or “Tap to Pay” in such a label; instead, use a generic label like “Look Up,” “Store Card,” “Verify,” or “Refund.”" + }, + { + "type": "paragraph", + "text": "When customers have other types of NFC-compatible cards or passes in Apple Wallet — such as loyalty, discount, and points cards — Tap to Pay on iPhone lets merchants read these items at the same time that they read a payment card or independently." + }, + { + "type": "paragraph", + "text": "If your app supports an independent loyalty card transaction, distinguish this flow from a payment-acceptance flow that uses Tap to Pay on iPhone. It works well to give merchants a separate, clearly labeled button to initiate a loyalty card transaction. To help merchants avoid choosing the wrong button by mistake, avoid including “Tap to Pay on iPhone,” “Tap to Pay,” or other payment-related terms in the label for a loyalty-transaction button." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Tap to Pay on iPhone Marketing guidelines" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Adding support for Tap to Pay on iPhone to your app — ProximityReader" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "January 17, 2024", + "Updated merchant education guidance." + ], + [ + "May 7, 2024", + "Updated to include guidance on enabling the feature and educating merchants." + ], + [ + "March 3, 2023", + "Enhanced guidance for educating merchants and improving their experience." + ], + [ + "September 14, 2022", + "Refined guidance on preparing Tap to Pay on iPhone and helping merchants learn how to use the feature." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Enabling Tap to Pay on iPhone", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Enabling-Tap-to-Pay-on-iPhone" + }, + { + "title": "Educating merchants", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Educating-merchants" + }, + { + "title": "Checking out", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Checking-out" + }, + { + "title": "Progress indicators", + "url": "/design/human-interface-guidelines/progress-indicators" + }, + { + "title": "SF Symbols", + "url": "/design/human-interface-guidelines/sf-symbols" + }, + { + "title": "Additional interactions", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Additional-interactions" + }, + { + "title": "Displaying results", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Displaying-results" + }, + { + "title": "alert", + "url": "/design/human-interface-guidelines/alerts" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Technologies", + "url": "https://developer.apple.com/design/human-interface-guidelines/technologies", + "category": "technologies", + "summary": "", + "sections": [], + "platforms": [], + "related": [ + { + "title": "AirPlay", + "url": "/design/human-interface-guidelines/airplay" + }, + { + "title": "Always On", + "url": "/design/human-interface-guidelines/always-on" + }, + { + "title": "App Clips", + "url": "/design/human-interface-guidelines/app-clips" + }, + { + "title": "Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay" + }, + { + "title": "Augmented reality", + "url": "/design/human-interface-guidelines/augmented-reality" + }, + { + "title": "CareKit", + "url": "/design/human-interface-guidelines/carekit" + }, + { + "title": "CarPlay", + "url": "/design/human-interface-guidelines/carplay" + }, + { + "title": "Game Center", + "url": "/design/human-interface-guidelines/game-center" + }, + { + "title": "Generative AI", + "url": "/design/human-interface-guidelines/generative-ai" + }, + { + "title": "HealthKit", + "url": "/design/human-interface-guidelines/healthkit" + }, + { + "title": "HomeKit", + "url": "/design/human-interface-guidelines/homekit" + }, + { + "title": "iCloud", + "url": "/design/human-interface-guidelines/icloud" + }, + { + "title": "ID Verifier", + "url": "/design/human-interface-guidelines/id-verifier" + }, + { + "title": "iMessage apps and stickers", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers" + }, + { + "title": "In-app purchase", + "url": "/design/human-interface-guidelines/in-app-purchase" + }, + { + "title": "Live Photos", + "url": "/design/human-interface-guidelines/live-photos" + }, + { + "title": "Mac Catalyst", + "url": "/design/human-interface-guidelines/mac-catalyst" + }, + { + "title": "Machine learning", + "url": "/design/human-interface-guidelines/machine-learning" + }, + { + "title": "Maps", + "url": "/design/human-interface-guidelines/maps" + }, + { + "title": "NFC", + "url": "/design/human-interface-guidelines/nfc" + }, + { + "title": "Photo editing", + "url": "/design/human-interface-guidelines/photo-editing" + }, + { + "title": "ResearchKit", + "url": "/design/human-interface-guidelines/researchkit" + }, + { + "title": "SharePlay", + "url": "/design/human-interface-guidelines/shareplay" + }, + { + "title": "ShazamKit", + "url": "/design/human-interface-guidelines/shazamkit" + }, + { + "title": "Sign in with Apple", + "url": "/design/human-interface-guidelines/sign-in-with-apple" + }, + { + "title": "Siri", + "url": "/design/human-interface-guidelines/siri" + }, + { + "title": "Tap to Pay on iPhone", + "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone" + }, + { + "title": "VoiceOver", + "url": "/design/human-interface-guidelines/voiceover" + }, + { + "title": "Wallet", + "url": "/design/human-interface-guidelines/wallet" + } + ], + "image_count": 0 + }, + { + "title": "VoiceOver", + "url": "https://developer.apple.com/design/human-interface-guidelines/voiceover", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "By supporting VoiceOver, you help people who are blind or have low vision access information in your app and navigate its interface and content when they can’t see the display." + }, + { + "type": "paragraph", + "text": "VoiceOver is supported in apps and games built for Apple platforms. It’s also supported in apps and games developed in Unity using Apple’s Unity plug-ins. For related guidance, see Accessibility." + } + ] + }, + { + "heading": "Descriptions", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "You inform VoiceOver about your app’s content by providing alternative text that explains your app’s interface and the content it displays." + }, + { + "type": "paragraph", + "text": "Provide alternative labels for all key interface elements. VoiceOver uses alternative labels (which aren’t visible onscreen) to audibly describe your app’s interface. System-provided controls have generic labels by default, but you should provide more descriptive labels that convey your app’s functionality. Add labels to any custom elements your app defines. Be sure to keep your descriptions up-to-date as your app’s interface and content change. For developer guidance, see Accessibility modifiers." + }, + { + "type": "paragraph", + "text": "Describe meaningful images. If you don’t describe key images in your app’s content, people can’t use VoiceOver to fully experience them within your app. Because VoiceOver helps people understand the interface surrounding images too, such as nearby captions, describe only the information the image itself conveys." + }, + { + "type": "paragraph", + "text": "Make charts and other infographics fully accessible. Provide a concise description of each infographic that explains what it conveys. If people can interact with the infographic to get more or different information, make these interactions available to people using VoiceOver, too. The accessibility APIs offer ways to represent custom interactive elements so that assistive technologies can help people use them. For guidance, see Charts." + }, + { + "type": "paragraph", + "text": "Exclude purely decorative images from VoiceOver. It’s unnecessary to describe images that are decorative and don’t convey useful or actionable information. Excluding these images shows respect for people’s time and reduces cognitive load when they use VoiceOver. For developer guidance, see accessibilityHidden(_:), accessibilityElement, and isAccessibilityElement." + } + ] + }, + { + "heading": "Navigation", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Use titles and headings to help people navigate your information hierarchy. The title is the first information someone receives from an assistive technology when arriving on a page or screen in your app. Offer unique titles that succinctly describe each page’s content and purpose. Likewise, use accurate section headings that help people build a mental model of each page’s information hierarchy." + }, + { + "type": "paragraph", + "text": "Specify how elements are grouped, ordered, or linked. Proximity, alignment, and other visible contextual cues help sighted people perceive the relationships between elements. Examine your app for places where relationships among elements are visual only. Then, describe these relationships to VoiceOver." + }, + { + "type": "paragraph", + "text": "VoiceOver reads elements in the same order people read content in the their active language and locale. For example, in US English, this is top-to-bottom, left-to-right. In the ungrouped example below, VoiceOver describes each image before moving on to the captions. In the grouped example, VoiceOver describes each image with its respective caption." + }, + { + "type": "paragraph", + "text": "Ungrouped related elements make it hard for VoiceOver to accurately describe the UI." + }, + { + "type": "paragraph", + "text": "Grouped related elements help VoiceOver accurately describe the UI." + }, + { + "type": "paragraph", + "text": "For developer guidance, see shouldGroupAccessibilityChildren." + }, + { + "type": "paragraph", + "text": "Inform VoiceOver when visible content or layout changes occur. People may find an unexpected content or layout change confusing because it means their mental map of the content is no longer accurate. It’s crucial to report visible changes so VoiceOver and other assistive technologies can help people update their understanding of the content. For developer guidance, see AccessibilityNotification." + }, + { + "type": "paragraph", + "text": "Support the VoiceOver rotor when possible. People can use an interface element called the VoiceOver rotor to navigate a document or webpage by headings, links, and other content types. You can help people navigate content in your app by identifying these elements to the rotor. The rotor can also bring up the braille keyboard. For developer guidance, see AccessibilityRotorEntry (SwiftUI), UIAccessibilityCustomRotor (UIKit), and NSAccessibilityCustomRotor (AppKit)." + } + ] + }, + { + "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": "Be mindful that custom gestures aren’t always accessible. When VoiceOver is turned on in visionOS, apps and games that define custom gestures don’t receive hand input by default. This ensures people can explore the interface using their voice, without an app responding to hand input at the same time. A person can opt out of this behavior by enabling Direct Gesture mode, which disables standard VoiceOver gestures and lets apps process hand input directly. For developer guidance, see Improving accessibility support in your visionOS app." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Accessibility" + }, + { + "type": "paragraph", + "text": "Inclusion" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Accessibility" + }, + { + "type": "paragraph", + "text": "VoiceOver" + }, + { + "type": "paragraph", + "text": "Supporting VoiceOver in your app" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "March 7, 2025", + "New page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Accessibility", + "url": "/design/human-interface-guidelines/accessibility" + }, + { + "title": "Descriptions", + "url": "/design/human-interface-guidelines/voiceover#Descriptions" + }, + { + "title": "Navigation", + "url": "/design/human-interface-guidelines/voiceover#Navigation" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/voiceover#Platform-considerations" + }, + { + "title": "visionOS", + "url": "/design/human-interface-guidelines/voiceover#visionOS" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/voiceover#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/voiceover#Related" + }, + { + "title": "Inclusion", + "url": "/design/human-interface-guidelines/inclusion" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/voiceover#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/voiceover#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/voiceover#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "Wallet", + "url": "https://developer.apple.com/design/human-interface-guidelines/wallet", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "People use their cards and passes in Wallet to make Apple Pay purchases, track their orders, confirm their identity, and streamline activities like boarding a plane, attending a concert, or receiving a discount." + }, + { + "type": "paragraph", + "text": "When you integrate Apple Wallet into your app, you can create custom passes and present them the moment people need them, securely verify an individual’s identity so they can access personal content, and offer detailed receipts and tracking information where it’s most convenient. For developer guidance, see Wallet." + } + ] + }, + { + "heading": "Passes", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Offer to add new passes to Wallet. When people do something that results in a new pass — like checking into a flight, purchasing an event ticket, or registering for a store reward program — you can present system-provided UI that helps them add the pass to Wallet with one tap (for developer guidance, see addPasses(_:withCompletionHandler:)). If people want to review a pass before adding it, you can display a custom view that displays the pass and provides an Add to Apple Wallet button; for developer guidance, see PKAddPassesViewController." + }, + { + "type": "paragraph", + "text": "Help people add a pass that they created outside of your app. If people create a pass using your website or another device, suggest adding it to Wallet the next time they open your app. If people decline your suggestion, don’t ask them again." + }, + { + "type": "paragraph", + "text": "Add related passes as a group. If your app generates multiple passes, like boarding passes for a multi-connection flight, add all passes at the same time so people don’t have to add each one individually. If people can receive a group of passes from your website — such as a set of tickets for an event — bundle them together so that people can download all of them at one time. For developer guidance, see Distributing and updating a pass." + }, + { + "type": "paragraph", + "text": "Display an Add to Apple Wallet button to let people add an existing pass that isn’t already in Wallet. If people previously declined your suggestion to add a pass to Wallet — or if they removed the pass — a button makes it easy to add it if they change their minds. You can display an Add to Apple Wallet button wherever the corresponding pass information appears in your app. For developer guidance, see PKAddPassButton. You can also display an Add to Apple Wallet badge in an email or on a webpage; for guidance, see Add to Apple Wallet guidelines." + }, + { + "type": "paragraph", + "text": "Let people jump from your app to their pass in Wallet. Wherever your app displays information about a pass that exists in Wallet, you can offer a link that opens it directly. Label the link something like “View in Wallet.”" + }, + { + "type": "paragraph", + "text": "Tell the system when your pass expires. Wallet automatically hides expired passes to reduce crowding, while also providing a button that lets people revisit them. To help ensure the system hides passes appropriately, set the expiration date, relevant date, and voided properties of each pass correctly; for developer guidance, see Pass." + }, + { + "type": "paragraph", + "text": "Always get people’s permission before deleting a pass from Wallet. For example, you could include an in-app setting that lets people specify whether they want to delete passes manually or have them removed automatically. If necessary, you can display an alert before deleting a pass." + }, + { + "type": "paragraph", + "text": "Help the system suggest a pass when it’s contextually relevant. Ideally, passes automatically appear when they’re needed so people don’t have to manually locate them. When you supply information about when and where your pass is relevant, the system can display a link to it on the Lock Screen when people are most likely to want it. For example, a gym membership card could appear on the Lock Screen as people enter the gym. For developer guidance, see Showing a Pass on the Lock Screen. Starting in iOS 18 and watchOS 11, the system starts a Live Activity for poster event ticket style passes when they’re relevant." + }, + { + "type": "paragraph", + "text": "Lock screen notification" + }, + { + "type": "paragraph", + "text": "Live Activity" + }, + { + "type": "paragraph", + "text": "Update passes as needed. Physical passes don’t typically change, but a digital pass can reflect updates to events. An airline boarding pass, for example, can automatically update to display flight delays and gate changes." + }, + { + "type": "paragraph", + "text": "Use change messages only for updates to time-critical information. A change message interrupts people’s current workflow, so it’s essential to send one only when you make an update they need to know about. For example, people need to know when there’s a gate change in a boarding pass, but they don’t need to know when a customer service phone number changes. Never use a change message for marketing or other noncritical communication. Change messages are available on a per-field basis; for developer guidance, see Adding a Web Service to Update Passes." + } + ] + }, + { + "heading": "Designing passes", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Wallet uses a consistent design aesthetic to strengthen familiarity and build trust. Instead of merely replicating the appearance of a physical item, design a clean, simple pass that looks at home in Wallet." + }, + { + "type": "paragraph", + "text": "Design a pass that looks great and works well on all devices. Passes can look different on different devices. For example, when a pass appears on Apple Watch, it doesn’t display all the images it displays when it appears on iPhone (for guidance, see Passes for Apple Watch). Don’t put essential information in elements that might be unavailable on certain devices. Also, don’t add padding to images; for example, watchOS crops white space from some images." + }, + { + "type": "paragraph", + "text": "Avoid using device-specific language. You can’t predict the device people will use to view your pass, so don’t write text that might not make sense on a particular device. For example, text that tells people to “slide to view” content doesn’t make sense when it appears on Apple Watch." + }, + { + "type": "paragraph", + "text": "Make your pass instantly identifiable. Using color — especially a color that’s linked to your brand — can help people recognize your pass as soon as they see it. Make sure that pass content remains comfortably readable against the background you choose." + }, + { + "type": "paragraph", + "text": "Keep the front of a pass uncluttered so people can get important information at a glance. Show essential information — like an event date or account balance — in the top-right area of the pass so people can still see it when the pass is collapsed in Wallet. Use the rest of the pass front to provide important information; consider putting extra information on the back of a pass (iOS) or in a details screen (watchOS)." + }, + { + "type": "paragraph", + "text": "Prefer an NFC-compatible pass. People appreciate having a contactless pass, because it means that they can just hold their device near a reader. If you support both NFC and a barcode or QR code, the code appears on the back of the pass (in iOS) or in the details screen (in watchOS). In iOS, you can display a QR code or barcode on the front of your pass if necessary for your design." + }, + { + "type": "paragraph", + "text": "Reduce image sizes for optimal performance. People can receive passes via email or a webpage. To make downloads as fast as possible, use the smallest image files that still look great." + }, + { + "type": "paragraph", + "text": "Provide an icon that represents your company or brand. The system includes your icon when displaying information about a relevant pass on the Lock Screen. Mail also uses the icon to represent your pass in an email message. You can use your app icon or design an icon for this purpose." + } + ] + }, + { + "heading": "Pass styles", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The system defines several pass styles for categories like boarding pass, coupon, store card, and event ticket. Pass styles specify the appearance and layout of content in your pass, and the information that the system needs to suggest your pass when it’s relevant (for guidance, see Passes)." + }, + { + "type": "paragraph", + "text": "Although each pass style is different, all styles display information using the basic layout areas shown below:" + }, + { + "type": "paragraph", + "text": "All passes display a logo image, and some can display additional images in other areas depending on the pass style. To display information in the layout areas, use the following PassFields." + }, + { + "type": "table", + "rows": [ + [ + "Field", + "Layout area", + "Use to provide…" + ], + [ + "Header", + "Essential", + "Critical information that needs to remain visible when the pass is collapsed in Wallet." + ], + [ + "Primary", + "Primary", + "Important information that helps people use the pass." + ], + [ + "Secondary and auxiliary", + "Secondary and auxiliary", + "Useful information that people might not need every time they use the pass." + ], + [ + "Back", + "Not shown in diagram", + "Supplemental details that don’t need to be on the pass front." + ] + ] + }, + { + "type": "paragraph", + "text": "In general, a pass can have up to three header fields, one primary field, up to four secondary fields, and up to four auxiliary fields. Depending on the amount of content you display in each field, some fields may not be visible." + }, + { + "type": "paragraph", + "text": "Display text only in pass fields. Don’t embed text in images — it’s not accessible and not all images are displayed on all devices — and avoid using custom fonts that might make text hard to read." + } + ] + }, + { + "heading": "Boarding passes", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the boarding pass style for train tickets, airline boarding passes, and other types of transit passes. Typically, each pass corresponds to a single trip with a specific starting and ending point." + }, + { + "type": "paragraph", + "text": "A boarding pass can display logo and footer images, and it can have up to two primary fields and up to five auxiliary fields." + } + ] + }, + { + "heading": "Coupons", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the coupon style for coupons, special offers, and other discounts. A coupon can display logo and strip images, and it can have up to four secondary and auxiliary fields, all displayed on one row." + } + ] + }, + { + "heading": "Store cards", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the store card style for store loyalty cards, discount cards, points cards, and gift cards. If an account related to a store card carries a balance, the pass usually shows the current balance." + }, + { + "type": "paragraph", + "text": "A store card can display logo and strip images, and it can have up to four secondary and auxiliary fields, all displayed on one row." + } + ] + }, + { + "heading": "Event tickets", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the event ticket pass style to give people entry into events like concerts, movies, plays, and sporting events. Typically, each pass corresponds to a specific event, but you can also use a single pass for several events, as with a season ticket." + }, + { + "type": "paragraph", + "text": "An event ticket can display logo, strip, background, or thumbnail images. However, if you supply a strip image, don’t include a background or thumbnail image. You can also include an extra row of up to four auxiliary fields. For developer guidance, see the row property of PassFields.AuxiliaryFields." + }, + { + "type": "paragraph", + "text": "In iOS 18 and later, the system defines an additional style for contactless event tickets called poster event ticket. Poster event tickets offer a rich visual experience that prominently features the event artwork, provides easy access to additional event information, and integrates with system apps like Weather and Maps." + }, + { + "type": "important", + "text": "ImportantPoster event tickets aren’t compatible with tickets that require a QR code or barcode for entry." + }, + { + "type": "paragraph", + "text": "A poster event ticket displays an event logo and background image, and can optionally display a separate ticket issuer or event company logo. The system uses metadata about your event to structure ticket information and suggest relevant actions. You must provide a required set of metadata in SemanticTags for all poster event tickets, and an additional set of required metadata depending on the event type — general, sports, or live performance. You can also add optional metadata to further enhance your ticket. For example, you can specify an admission level for a live performance, like General Admission, which the system displays with the seating information. For developer guidance, see Supporting semantic tags in Wallet passes." + }, + { + "type": "paragraph", + "text": "The system uses the metadata that you provide to generate a Maps shortcut to the venue directions and an event guide below the ticket when in the Wallet app. The event guide provides convenient access to information like the weather forecast and venue map, and to quick actions like checking the baggage policy and ordering food. You can display a minimum of one and up to four quick action buttons in the event guide; if you include more than four, the system collapses them into a menu. You can optionally include additional ticket information, such as pre-paid parking details, which the system also displays below the ticket." + }, + { + "type": "paragraph", + "text": "Additional ticket information, Maps shortcut, and event guide tiles below the ticket in the Wallet app" + }, + { + "type": "paragraph", + "text": "Event guide" + }, + { + "type": "paragraph", + "text": "Create a vibrant and engaging background. As the centerpiece of a poster event ticket, your background image serves as a visual representation of the event. Limit text in your artwork, and create an image that’s easily identifiable to help people quickly find their ticket among other passes in their Wallet app. If your background image is a solid color or includes a solid color in the footer, consider setting a footer background color to better blend the background image with the footer." + }, + { + "type": "paragraph", + "text": "Position your background image in the safe area. The system displays ticket information in the header and footer, which overlap the background image. To ensure that the content in your artwork isn’t covered, position it in the safe area. For developer guidance, see footerBackgroundColor in Pass." + }, + { + "type": "paragraph", + "text": "Ensure sufficient contrast so that ticket information is easy to read. By default, the system applies a gradient in the header and a blur effect in the footer of your poster event ticket to provide sufficient contrast between the background image and ticket information. Consider adjusting the gradient and blur effect if you need more contrast. The system can also automatically determine the best text color for ticket information and labels based on your background image. If you choose to customize text colors, make sure to select a color that provides sufficient contrast, especially if you set a footer background color or a seat section color to support wayfinding. For developer guidance, see useAutomaticColors in Pass and seatSectionColor in SemanticTagType.Seat." + }, + { + "type": "paragraph", + "text": "Consider using the additional information tile for extra event details. When you have more information about the event that people may find helpful, the additional information tile below the ticket is a great place to put it. If you have additional information that’s essential to display on the front of the ticket, keep the text short to avoid cluttering the footer. For developer guidance, see additionalTicketAttributes in SemanticTags and PassFields.AdditionalInfoFields." + }, + { + "type": "paragraph", + "text": "Continue to support event tickets for earlier versions of iOS. People expect contactless event tickets to work, regardless of their device’s software version. Continue to provide primary, secondary, and auxiliary information in PassFields and image assets for your event ticket. This enables the system to automatically generate the appropriate ticket style for a person’s device; otherwise, your ticket appears empty on devices running earlier versions of iOS." + } + ] + }, + { + "heading": "Generic passes", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Use the generic style for a type of pass that doesn’t fit into the other categories, such as a gym membership card or coat-check claim ticket. A generic pass can display logo and thumbnail images, and it can have up to four secondary and auxiliary fields, all displayed on one row." + } + ] + }, + { + "heading": "Passes for Apple Watch", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "On Apple Watch, Wallet displays passes in a scrolling carousel of cards. People can add your pass to their Apple Watch even if you don’t create a watch-specific app, so it’s important to understand how your pass can look on the device." + }, + { + "type": "paragraph", + "text": "People can tap a pass on their Apple Watch to reveal a details screen that displays additional information in a scroll view. In some cases, people can also tap a specific transaction to get more information." + }, + { + "type": "paragraph", + "text": "Each pass style specifies the fields and images that can appear in the basic layout areas shown below:" + }, + { + "type": "paragraph", + "text": "If some information doesn’t fit within the layout areas, the system displays it in the scrolling details screen." + }, + { + "type": "important", + "text": "ImportantIn every style, watchOS crops the strip image to fit the aspect ratio of the card interface and may crop white space from other images." + } + ] + }, + { + "heading": "Order tracking", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "When you support order tracking, Wallet can display information about an order a customer placed through your app or website, updating the information whenever the status of the order changes. In iOS 17 and later, you can help people start tracking their order right from your app or website and offer additional ways to add their order to Wallet." + }, + { + "type": "paragraph", + "text": "Wallet presents a dashboard that displays a customer’s active and completed orders. People can choose an order to view details about it, like the items they ordered and fulfillment information for shipping and pickup." + }, + { + "type": "paragraph", + "text": "Dashboard" + }, + { + "type": "paragraph", + "text": "The Wallet Orders schema defines the properties you use to provide order data like product descriptions, order status, contact information, and shipping and pickup details, including estimated arrival dates, addresses, tracking numbers, and pickup instructions. Wallet displays the information you supply within consistent, system-defined interfaces. To help people get the information they need quickly and conveniently, supply as much information as you can, using the properties that match your order processes." + }, + { + "type": "paragraph", + "text": "Make it easy for people to add an order to Wallet. For example, when a customer completes an Apple Pay transaction in your app or website, use PKPaymentOrderDetails (app) or ApplePayPaymentOrderDetails (web) to automatically add the order to Wallet. In iOS 17 and later, you can use AddOrderToWalletButton to display the system-provided Track with Apple Wallet button in relevant areas of your app or website — such as in pages for order confirmation, status, or tracking — or in emails to customers. If a person already added an order to Wallet, trying to add it again opens Wallet and displays the order." + }, + { + "type": "paragraph", + "text": "Make information about an order available immediately after people place it. People need to confirm that their order was received, even when payment, processing, and fulfillment are still pending. If you won’t have details until a later time, provide the data you have at the time of the order and supply a status description like “Check back later for full order details.”" + }, + { + "type": "paragraph", + "text": "Provide fulfillment information as soon as it’s available, and keep the status up to date. When you supply fulfillment data or you change the status of an order, the system updates the order information and can automatically send a notification to customers. The system uses the fulfillment status you report to update the order’s current status to a value like Order Placed, Processing, Ready for Pickup, Picked Up, Out for Delivery, Delivered, or — if something goes wrong — Issue or Canceled. For guidance on describing a status, see Displaying order and fulfillment details." + }, + { + "type": "paragraph", + "text": "Supply a high-resolution logo image that uses a nontransparent background. The system displays your logo image in the dashboard and detail view, so you want to make sure that people can instantly recognize it at various sizes. Use the PNG or JPEG format to create a logo image that measures 300x300 pixels. To help ensure that your logo image renders correctly, be sure to use a nontransparent background. For developer guidance, see logo." + }, + { + "type": "paragraph", + "text": "Supply distinct, high-resolution product images that use nontransparent backgrounds. The system displays a product’s image — along with descriptive information you supply — in the detail views, order dashboard, and notifications for an order or a fulfillment. When creating a product image, use a straightforward depiction and a solid, nontransparent background. Showing a product in a “lifestyle” context or against a busy background can make the item hard to distinguish at small sizes. For each product, use the PNG or JPEG format to create an image that measures 300x300 pixels." + }, + { + "type": "paragraph", + "text": "In general, keep text brief. People appreciate being able to read text at a glance, and the system can truncate text that’s too long." + }, + { + "type": "paragraph", + "text": "Use clear, approachable language, and localize the text you provide. You want to make sure that all your customers can read the information in an order. Also, make sure the price you show matches the final price the customer confirmed." + } + ] + }, + { + "heading": "Displaying order and fulfillment details", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "An order gives people ways to contact the merchant and displays details about their Apple Pay purchase, including fulfillment status and per-item information." + }, + { + "type": "paragraph", + "text": "Provide a link to an area where people manage their order. When you provide a universal link, people can open your order management area even if they don’t have your app installed. To learn more about universal links, see Allowing apps and websites to link to your content; for developer guidance, see Order." + }, + { + "type": "paragraph", + "text": "Clearly describe each item so people can verify that their order contains everything they expect. You can use the LineItem property to provide information like a product’s price, name, and image. An order lists the line items for every item the customer ordered; a fulfillment lists only the line items that fulfillment includes. When appropriate, you can also attach a PDF receipt to an individual transaction related to an order." + }, + { + "type": "paragraph", + "text": "Supply a prioritized list of your apps that might be installed on the device. The system uses this list when it needs to display a link to your app within the order details view. For example, if you provide multiple apps and more than one of them is installed on the device, the system displays a link to the installed app that’s highest on your list. If none of your apps are installed on the device, the system displays a link to the first app on your list. For developer guidance, see Order." + }, + { + "type": "paragraph", + "text": "Avoid sending duplicate notifications. For example, you can tell the system to avoid sending order-related notifications through Wallet when the customer has one of your associated apps installed." + }, + { + "type": "paragraph", + "text": "Make it easy for customers to contact the merchant. Provide multiple contact methods, so people can choose the one that works best for them. At minimum, you need to provide a link to the merchant’s website or landing page, but you can also provide a Messages for Business link, a phone number, an email address, and a link to a support page. When people choose the Contact button in an order, the system displays a menu of the contact methods you supply. For developer guidance, see Merchant." + }, + { + "type": "paragraph", + "text": "Help people track their order. A multi-item order can have multiple fulfillments, where each fulfillment is either shipping or pickup. For example, if a customer orders a pair of shoes and a T-shirt, the customer might want to have one item shipped, while picking up the other. Regardless of fulfillment type, you need to supply enough information for people to know where their items are and when to expect them at the destination they specified. In addition to an estimated time of arrival, here’s some information that people particularly appreciate:" + }, + { + "type": "list", + "items": [ + "A link that opens the carrier’s website to a page with information about a shipping fulfillment. When possible, provide a direct link — in addition to a tracking number — so people can easily view the most up-to-date shipping information. If necessary, display this link on any intermediate order-tracking page you open.", + "A scannable barcode when one is required to pick up the order in a pickup fulfillment. It’s convenient when people can offer the barcode from within Wallet instead of finding it in an email or webpage.", + "Clear, detailed instructions that can help people receive or pick up their order." + ] + }, + { + "type": "paragraph", + "text": "Keep the fulfillment screen centered on order tracking. For example, if you recommend your app or other services to customers, be sure to prioritize order-tracking information over other content in the screen." + }, + { + "type": "paragraph", + "text": "Choose shipping-fulfillment values that match the details you have about the shipping process. If you know the carrier, enter its name in the carrier property; otherwise, leave the default “Track Shipment” value. If you can access details about a carrier’s interim shipping steps — such as when a fulfillment is on the way or out for delivery — indicate each step by using specific status values like onTheWay, outForDelivery, or delivered. In contrast, if you don’t have access to a carrier’s shipping details, use the shipped status. In both cases, provide a tracking link (when one is available) so people can track their order on their own. For developer guidance, see ShippingFulfillment." + }, + { + "type": "paragraph", + "text": "Keep customers informed through relevant fulfillment status descriptions. A great status message is approachable, accurate, and clearly related to the status it describes. In addition to supplying information that helps people understand the status of their order, a status message also gives you an opportunity to use your brand’s communication style." + }, + { + "type": "paragraph", + "text": "Be direct and thorough when describing an Issue or Canceled status. People generally need to know why there’s a problem and what they can do about it." + } + ] + }, + { + "heading": "Identity verification", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "On iPhone running iOS 16 and later, people can store an ID card in Wallet, and later allow an app or App Clip to access information on the card to verify their identity without leaving their current context. For example, a person might need to confirm their identity when they apply for a credit card within their banking app. To learn how to support in-person mobile ID verification, see ID Verifier." + }, + { + "type": "note", + "text": "Developer noteApple doesn’t create or see the ID documents that people add to Wallet, and when people agree to share identifying information with your app, you receive only encrypted data that isn’t readable on the device. For developer guidance, see Requesting identity data from a Wallet pass." + }, + { + "type": "paragraph", + "text": "To help you offer a consistent experience that people can trust, Apple provides a Verify with Wallet button you can use in your app when you need to ask for identify verification. The button reveals a sheet that describes your request and lets people agree to share their information or cancel." + }, + { + "type": "paragraph", + "text": "Present a Wallet verification option only when the device supports it. If the current device can’t return the identify information you request, don’t display a Verify with Apple Wallet button. Be prepared to present a fallback view that offers a different verification method if Verify with Apple Wallet isn’t available; for developer guidance, see VerifyIdentityWithWalletButton." + }, + { + "type": "paragraph", + "text": "Ask for identity information only at the precise moment you need it. People can be suspicious of a request for personal information if it doesn’t seem to be related to their current action. If your app needs identity verification, for example, wait to ask for this information until people are completing the process or transaction that requires it; don’t request verification before people are ready to start the process or when they’re simply creating an account." + }, + { + "type": "paragraph", + "text": "Clearly and succinctly describe the reason you need the information you’re requesting. You must write text that explains why people need to share identity information with your app (this text is called a purpose string or usage description string). The system displays your purpose string in the verification sheet so people can make an informed decision. Here are a couple of examples:" + }, + { + "type": "table", + "rows": [ + [ + "To verify…", + "To support…", + "Example purpose string" + ], + [ + "Identity", + "Opening an account for which proof of identity is legally required to prevent fraud", + "Federal law requires this information to verify your identity and also to help [App Name] prevent fraud." + ], + [ + "Driving privilege", + "Renting a vehicle that requires legal driving privileges", + "Applicable state law requires [App Name] to verify your driving privileges." + ] + ] + }, + { + "type": "paragraph", + "text": "For each purpose string, aim for a brief, complete sentence that’s direct, specific, and easy for everyone to understand. Use sentence case, avoid passive voice, and include a period at the end." + }, + { + "type": "paragraph", + "text": "Ask only for the data you actually need. People may lose trust in your app if you ask for more data than you need to complete the current task or action. For example, if you need to ensure that a customer is at least a certain age, use a request that specifies an age threshold; avoid requesting the customer’s current age or birth date. For developer guidance, see age(atLeast:)." + }, + { + "type": "paragraph", + "text": "Clearly indicate whether you will keep the data and — if you need to keep it — specify how long you’ll do so. To help people trust your app, it’s essential to explain how long you might need to keep the personal information they agree to share with you. When you use PassKit APIs to specify a duration — such as a particular period, indefinitely, or only as long as it takes to complete the current verification — the system automatically displays explanatory content in the verification sheet. For developer guidance, see PKIdentityIntentToStore." + }, + { + "type": "paragraph", + "text": "Choose the system-provided verification button that matches your use case and the visual design of your app. The system provides the following button labels to support various use cases:" + }, + { + "type": "table", + "rows": [ + [ + "Button type", + "Consider using when…" + ], + [ + "", + "Your app can complete the current transaction after you verify a person’s age. An example transaction is making a car available to lease." + ], + [ + "", + "Your app can complete the current transaction after you verify a person’s identity. An example transaction is a car rental." + ], + [ + "", + "Verify with Wallet forms one part of a verification process that also requires people to supply additional information not provided by Verify with Wallet, such as a Social Security number or phone number. Examples include opening a financial account or performing a background check." + ], + [ + "", + "Your app can complete the current verification flow without additional steps, but the “Verify Age,” “Verify Identity,” and “Continue” button labels aren’t appropriate for your use case. An example is an app that helps people sign up for a government service." + ] + ] + }, + { + "type": "paragraph", + "text": "All button labels are also available in a multiline variant that the system automatically uses when horizontal space is constrained. For developer guidance, see PKIdentityButton.Label." + }, + { + "type": "paragraph", + "text": "The verification button always uses white letters on a black background. You can choose the style that includes a light outline if you need to ensure that the button contrasts well with a dark background in your app. In addition, you can use the cornerRadius property to adjust the verification button’s corners to match other related buttons in your interface. For developer guidance, see PKIdentityButton.Style.blackOutline." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, visionOS, or watchOS. Not supported in tvOS." + } + ] + }, + { + "heading": "Pass image dimensions", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "As you design images for your wallet passes, create PNG files and use the following values for guidance." + }, + { + "type": "table", + "rows": [ + [ + "Image", + "Supported pass styles", + "Filename", + "Dimensions (pt)" + ], + [ + "Logo", + "Boarding pass, coupon, store card, event ticket, generic pass", + "logo.png", + "Any, up to 160x50" + ], + [ + "Primary logo", + "Poster event ticket", + "primaryLogo.png", + "Any, up to 126x30" + ], + [ + "Secondary logo", + "Poster event ticket", + "secondaryLogo.png", + "Any, up to 135x12" + ], + [ + "Icon", + "All", + "icon.png", + "38x38" + ], + [ + "Background", + "Event ticket, poster event ticket", + "background.png (event ticket), artwork.png (poster event ticket)", + "180x220 (event ticket), 358x448 (poster event ticket)" + ], + [ + "Strip", + "Coupon, store card, event ticket", + "strip.png", + "375x144 (coupon, store card), 375x98 (event ticket)" + ], + [ + "Footer", + "Boarding pass", + "footer.png", + "Any, up to 286x15" + ], + [ + "Thumbnail", + "Event ticket, generic pass", + "thumbnail.png", + "90x90" + ] + ] + }, + { + "type": "note", + "text": "NoteDimensions for the logo, primary logo, and secondary logo images are the maximum — not the required — values. For example, if you create a primary logo image that measures 30x30 points, you don’t need to add unnecessary padding so that it measures the maximum 126x30 points." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Apple Pay" + }, + { + "type": "paragraph", + "text": "ID Verifier" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "FinanceKitUI" + }, + { + "type": "paragraph", + "text": "FinanceKit" + }, + { + "type": "paragraph", + "text": "PassKit (Apple Pay and Wallet)" + }, + { + "type": "paragraph", + "text": "Wallet Passes" + }, + { + "type": "paragraph", + "text": "Wallet Orders" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "January 17, 2025", + "Added specifications for pass image dimensions." + ], + [ + "December 18, 2024", + "Added guidance for the poster event ticket style." + ], + [ + "September 12, 2023", + "Added guidance for helping people add orders to Wallet." + ], + [ + "February 20, 2023", + "Enhanced guidance for presenting order-tracking information and added artwork." + ], + [ + "November 30, 2022", + "Added guidance to include a carrier name in status information for a shipping fulfillment." + ], + [ + "September 14, 2022", + "Added guidelines for using Verify with Wallet, updated guidance on providing shipping status values and descriptions, and consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Passes", + "url": "/design/human-interface-guidelines/wallet#Passes" + }, + { + "title": "Designing passes", + "url": "/design/human-interface-guidelines/wallet#Designing-passes" + }, + { + "title": "Passes for Apple Watch", + "url": "/design/human-interface-guidelines/wallet#Passes-for-Apple-Watch" + }, + { + "title": "Pass styles", + "url": "/design/human-interface-guidelines/wallet#Pass-styles" + }, + { + "title": "Boarding passes", + "url": "/design/human-interface-guidelines/wallet#Boarding-passes" + }, + { + "title": "Coupons", + "url": "/design/human-interface-guidelines/wallet#Coupons" + }, + { + "title": "Store cards", + "url": "/design/human-interface-guidelines/wallet#Store-cards" + }, + { + "title": "Event tickets", + "url": "/design/human-interface-guidelines/wallet#Event-tickets" + }, + { + "title": "Generic passes", + "url": "/design/human-interface-guidelines/wallet#Generic-passes" + }, + { + "title": "Order tracking", + "url": "/design/human-interface-guidelines/wallet#Order-tracking" + }, + { + "title": "Displaying order and fulfillment details", + "url": "/design/human-interface-guidelines/wallet#Displaying-order-and-fulfillment-details" + }, + { + "title": "Identity verification", + "url": "/design/human-interface-guidelines/wallet#Identity-verification" + }, + { + "title": "ID Verifier", + "url": "/design/human-interface-guidelines/id-verifier" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/wallet#Platform-considerations" + }, + { + "title": "Specifications", + "url": "/design/human-interface-guidelines/wallet#Specifications" + }, + { + "title": "Pass image dimensions", + "url": "/design/human-interface-guidelines/wallet#Pass-image-dimensions" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/wallet#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/wallet#Related" + }, + { + "title": "Apple Pay", + "url": "/design/human-interface-guidelines/apple-pay" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/wallet#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/wallet#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/wallet#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "iCloud", + "url": "https://developer.apple.com/design/human-interface-guidelines/icloud", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "A fundamental aspect of iCloud is transparency. People don’t need to know where content resides. They can just assume they’re always accessing the latest version." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Make it easy to use your app with iCloud. People turn on iCloud in Settings and expect apps to work with it automatically. If you think people might want to choose whether to use iCloud with your app, show a simple option the first time your app opens that provides a choice between using iCloud for all data or not at all." + }, + { + "type": "paragraph", + "text": "Avoid asking which documents to keep in iCloud. Most people expect all of their content to be available in iCloud and don’t want to manage the storage of individual documents. Consider how your app handles and exposes content, and try to perform more file-management tasks automatically." + }, + { + "type": "paragraph", + "text": "Keep content up to date when possible. In an app that supports iCloud, it’s best when people always have access to the most recent content. However, you need to balance this experience with respect to device storage and bandwidth constraints. If your app works with very large documents, it may be better to let people control when updated content is downloaded. If your app fits in this category, design a way to indicate that a more recent version of a document is available in iCloud. When a document is updating, provide subtle feedback if the download takes more than a few seconds." + }, + { + "type": "paragraph", + "text": "Respect iCloud storage space. iCloud is a finite resource for which people pay. Use iCloud to store information people create and understand, and avoid using it for app resources or content you can regenerate. Even if your app doesn’t implement iCloud support, remember that iCloud backups include the contents of every app’s Documents folder. To avoid using up too much space, be picky about the content you place in the Documents folder." + }, + { + "type": "paragraph", + "text": "Make sure your app behaves appropriately when iCloud is unavailable. If someone manually turns off iCloud or turns on Airplane Mode, you don’t need to display an alert notifying them iCloud is unavailable. However, it may still be helpful to unobtrusively let people know that changes they make won’t be available on other devices until they restore iCloud access." + }, + { + "type": "paragraph", + "text": "Keep app state information in iCloud. In addition to storing documents and other files, you can use iCloud to store settings and information about the state of your app. For example, a magazine app might store the last page viewed so when the app is opened on another device, someone can continue reading from where they left off. If you use iCloud to store settings, make sure it’s for ones people want applied to all of their devices. For example, some settings might be more useful at work than at home." + }, + { + "type": "paragraph", + "text": "Warn about the consequences of deleting a document. When someone deletes a document in an app that supports iCloud, the document is removed from iCloud and all other devices too. Show a warning and ask for confirmation before performing the deletion." + }, + { + "type": "paragraph", + "text": "Make conflict resolution prompt and easy. To the extent possible, try to detect and resolve version conflicts automatically. If this can’t be done, display an unobtrusive notification that makes it easy to differentiate and choose between the conflicting versions. Ideally, conflict resolution occurs as early as possible, so time isn’t wasted in the wrong version." + }, + { + "type": "paragraph", + "text": "Include iCloud content in search results. People with iCloud accounts assume their content is universally available, and they expect search results to reflect this perspective." + }, + { + "type": "paragraph", + "text": "For games, consider saving player progress in iCloud. Although you can implement this functionality yourself, the GameSave framework offers an efficient solution. It synchronizes save data across devices and offers built-in alerts you can use to help players handle syncing issues during offline play or when conflicts arise. Alternatively, you can implement custom UI that uses GameSave data to resolve these situations. For developer guidance, see GameSave." + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "CloudKit" + }, + { + "type": "paragraph", + "text": "GameSave" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "June 9, 2025", + "Added guidance for synchronizing game data through iCloud." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/icloud#Best-practices" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/icloud#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/icloud#Resources" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/icloud#Developer-documentation" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/icloud#Change-log" + } + ], + "image_count": 0 + }, + { + "title": "iMessage apps and stickers", + "url": "https://developer.apple.com/design/human-interface-guidelines/imessage-apps-and-stickers", + "category": "technologies", + "summary": "", + "sections": [ + { + "heading": "Overview", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "An iMessage app or sticker pack is available within the context of a Messages conversation and also in effects in both Messages and FaceTime. You can create an iMessage app or sticker pack as a standalone app or as an app extension within your iOS or iPadOS app. For developer guidance, see Messages and Adding Sticker packs and iMessage apps to the system Stickers app, Messages camera, and FaceTime." + } + ] + }, + { + "heading": "Best practices", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "Prefer providing one primary experience in your iMessage app. People are in a conversational flow when they choose your app, so your functionality or content needs to be easy to understand and immediately available. If you want to provide multiple types of functionality or different collections of content, consider creating a separate iMessage app for each one." + }, + { + "type": "paragraph", + "text": "Consider surfacing content from your iOS or iPadOS app. For example, your iMessage app could offer app-specific information that people might want to share — such as a shopping list or a trip itinerary — or support a simple, collaborative task, like deciding where to go for a meal or which movie to watch." + }, + { + "type": "paragraph", + "text": "Present essential features in the compact view. People can experience your iMessage app in a compact view that appears below the message transcript, or they can expand the view to occupy most of the window. Make sure the most frequently used items are available in the compact view, reserving additional content and features for the expanded view." + }, + { + "type": "paragraph", + "text": "In general, let people edit text only in the expanded view. The compact view occupies roughly the same space as the keyboard. To ensure that the iMessage app’s content remains visible while people edit, display the keyboard in the expanded view." + }, + { + "type": "paragraph", + "text": "Create stickers that are expressive, inclusive, and versatile. Whether your stickers are rich, static images or short animations, make sure that each one remains legible against a wide range of backgrounds and when rotated or scaled. You can also use transparency to help people visually integrate a sticker with text, photos, and other stickers." + }, + { + "type": "paragraph", + "text": "For each sticker, provide a localized alternative description. VoiceOver can help people use your sticker pack by speaking a sticker’s alternative description." + } + ] + }, + { + "heading": "Icon sizes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "The icon for an iMessage app or sticker pack can appear in Messages, the App Store, notifications, and Settings. After people install your iMessage app or sticker pack, its icon also appears in the app drawer in the Messages app." + }, + { + "type": "paragraph", + "text": "You supply a square-cornered icon for each extension you offer, and the system automatically applies a mask that rounds the corners." + }, + { + "type": "paragraph", + "text": "To ensure that your icon looks great in any context and on various devices, create a square-cornered icon in the following sizes:" + }, + { + "type": "table", + "rows": [ + [ + "Usage", + "@2x (pixels)", + "@3x (pixels)" + ], + [ + "Messages, notifications", + "148x110", + "-" + ], + [ + "", + "143x100", + "-" + ], + [ + "", + "120x90", + "180x135" + ], + [ + "", + "64x48", + "96x72" + ], + [ + "", + "54x40", + "81x60" + ], + [ + "Settings", + "58x58", + "87x87" + ], + [ + "App Store", + "1024x1024", + "1024x1024" + ] + ] + } + ] + }, + { + "heading": "Sticker sizes", + "level": 3, + "content": [ + { + "type": "paragraph", + "text": "Messages supports small, regular, and large stickers. Pick the size that works best for your content and prepare all of your stickers at that size; don’t mix sizes within a single sticker pack. Messages displays stickers in a grid, organized differently for different sizes." + }, + { + "type": "paragraph", + "text": "Small" + }, + { + "type": "paragraph", + "text": "Regular" + }, + { + "type": "paragraph", + "text": "Large" + }, + { + "type": "paragraph", + "text": "Create your sticker images using the following @3x dimensions for the sticker size you chose. If necessary, the system generates @2x and @1x versions by downscaling the images at runtime. For developer guidance, see MSStickerSize." + }, + { + "type": "table", + "rows": [ + [ + "Sticker size", + "@3x dimensions (pixels)" + ], + [ + "Small", + "300x300" + ], + [ + "Regular", + "408x408" + ], + [ + "Large", + "618x618" + ] + ] + }, + { + "type": "paragraph", + "text": "A sticker file must be 500 KB or smaller in size. For each supported format, the table below provides guidance for using transparency and animation." + }, + { + "type": "table", + "rows": [ + [ + "Format", + "Transparency", + "Animation" + ], + [ + "PNG", + "8-bit", + "No" + ], + [ + "APNG", + "8-bit", + "Yes" + ], + [ + "GIF", + "Single-color", + "Yes" + ], + [ + "JPEG", + "No", + "No" + ] + ] + } + ] + }, + { + "heading": "Platform considerations", + "level": 2, + "content": [ + { + "type": "paragraph", + "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." + } + ] + }, + { + "heading": "Related", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "iMessage Apps and Stickers" + } + ] + }, + { + "heading": "Developer documentation", + "level": 4, + "content": [ + { + "type": "paragraph", + "text": "Messages" + }, + { + "type": "paragraph", + "text": "Adding Sticker packs and iMessage apps to the system Stickers app, Messages camera, and FaceTime — Messages" + } + ] + }, + { + "heading": "Change log", + "level": 2, + "content": [ + { + "type": "table", + "rows": [ + [ + "Date", + "Changes" + ], + [ + "May 2, 2023", + "Consolidated guidance into one page." + ] + ] + } + ] + } + ], + "platforms": [], + "related": [ + { + "title": "Best practices", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Best-practices" + }, + { + "title": "Specifications", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Specifications" + }, + { + "title": "Icon sizes", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Icon-sizes" + }, + { + "title": "Sticker sizes", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Sticker-sizes" + }, + { + "title": "Platform considerations", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Platform-considerations" + }, + { + "title": "Resources", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Resources" + }, + { + "title": "Related", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Related" + }, + { + "title": "Developer documentation", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Developer-documentation" + }, + { + "title": "Videos", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Videos" + }, + { + "title": "Change log", + "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Change-log" + } + ], + "image_count": 0 + } + ] +} \ No newline at end of file diff --git a/references/hig-color.md b/references/hig-color.md new file mode 100644 index 0000000..1b3317b --- /dev/null +++ b/references/hig-color.md @@ -0,0 +1,94 @@ +# HIG: Color & Dark Mode + +Source: [Apple HIG — Color](https://developer.apple.com/design/human-interface-guidelines/color) | [Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode) + +## Best Practices + +- Don't use the same color to mean different things — use color consistently for status and interactivity +- All colors must work in light, dark, AND increased contrast contexts +- Even single-appearance apps must provide both light and dark colors for Liquid Glass adaptivity +- Test colors under different lighting conditions (bright sunlight, dim light) +- Test on multiple devices (True Tone displays adapt white point) +- Avoid hard-coding system color values — use `Color` API +- Use wide color (Display P3) for richer, more saturated colors on compatible displays +- Use asset catalog Color Sets with light/dark variants + +## Inclusive Color + +- Never rely solely on color to differentiate objects or communicate info +- Provide text labels, glyph shapes, or patterns as alternatives +- Ensure sufficient contrast so icons and text don't blend with background +- Consider cultural color meanings (red = danger in some cultures, positive in others) + +## System Colors (SwiftUI) + +red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown + +- visionOS uses default dark color values +- iOS/iPadOS has 6 system grays: `gray` (SwiftUI) = `systemGray` (UIKit), plus `systemGray2`-`systemGray6` + +## iOS/iPadOS Dynamic Background Colors + +Two sets — **system** and **grouped** — each with primary, secondary, tertiary: + +| Level | Use for | +|-------|---------| +| Primary | Overall view background | +| Secondary | Grouping content within the overall view | +| Tertiary | Grouping content within secondary elements | + +Use **grouped** set with grouped table views; **system** set otherwise. + +## Foreground Colors (iOS) + +| Color | Use | UIKit API | +|-------|-----|-----------| +| Label | Primary content text | `label` | +| Secondary label | Secondary content | `secondaryLabel` | +| Tertiary label | Tertiary content | `tertiaryLabel` | +| Quaternary label | Quaternary content | `quaternaryLabel` | +| Placeholder text | Control placeholders | `placeholderText` | +| Separator | Allows underlying content through | `separator` | +| Opaque separator | Fully opaque | `opaqueSeparator` | +| Link | Hyperlink text | `link` | + +## Liquid Glass Color + +- Liquid Glass has no inherent color — takes on colors from content behind it +- Apply color sparingly — reserve for emphasis (status indicators, primary actions) +- For primary actions, color the background (not symbols/text) +- Don't apply color to multiple control backgrounds +- Symbols/text on Liquid Glass can have color (e.g., selected tab bar item) +- Avoid similar colors in control labels over colorful backgrounds — prefer monochromatic + +## Color Management + +- Apply color profiles to images (sRGB for most, Display P3 for wide color) +- Wide color: P3 profile at 16 bits/channel, export as PNG +- Provide color space-specific variants if P3 gradients appear clipped on sRGB displays + +## Dark Mode + +- Don't offer app-specific appearance toggle — respect system setting +- Ensure content is legible in both modes, including with Increase Contrast + Reduce Transparency +- Dark palette uses dimmer backgrounds, brighter foregrounds (not simple inversions) +- Use semantic Color Set assets with light/dark variants — avoid hard-coded values +- Minimum contrast ratio: 4.5:1; aim for 7:1 especially in small text +- Soften white backgrounds slightly to prevent glowing in dark contexts + +### iOS/iPadOS Dark Mode + +- Two background levels: **base** (dimmer, recedes) and **elevated** (brighter, advances) +- System auto-switches base to elevated for popovers, modal sheets, foreground apps +- Use system background colors to maintain these visual distinctions + +### macOS Dark Mode + +- Desktop tinting: window backgrounds pick up color from desktop picture (graphite accent) +- Add transparency to custom component backgrounds (neutral state only) for tinting harmony + +## Platform-Specific Notes + +- **tvOS:** Limited color palette coordinating with app logo; don't use only color to indicate focus +- **visionOS:** Use color sparingly on glass; prefer bold text/large areas; keep brightness balanced +- **watchOS:** Background color should communicate, not just decorate; avoid full-screen background color in long-duration views diff --git a/references/hig-components.md b/references/hig-components.md new file mode 100644 index 0000000..efbb4a8 --- /dev/null +++ b/references/hig-components.md @@ -0,0 +1,62 @@ +# HIG: Components & Patterns + +Source: [Apple HIG — Components](https://developer.apple.com/design/human-interface-guidelines/components) | [Modality](https://developer.apple.com/design/human-interface-guidelines/modality) | [Searching](https://developer.apple.com/design/human-interface-guidelines/searching) + +## Component Categories + +### Content +Charts, Image views, Text views, Web views + +### Layout and Organization +Boxes, Collections, Column views, Disclosure controls, Labels, Lists and tables, Lockups, Outline views, Split views, Tab views + +### Menus and Actions +Activity views, Buttons, Context menus, Dock menus, Edit menus, Home Screen quick actions, Menus, Ornaments, Pop-up buttons, Pull-down buttons, The menu bar, Toolbars + +### Navigation and Search +Path controls, Search fields, Sidebars, Tab bars, Token fields + +### Presentation +Action sheets, Alerts, Page controls, Panels, Popovers, Scroll views, Sheets, Windows + +### Selection and Input +Color wells, Combo boxes, Digit entry views, Image wells, Pickers, Segmented controls, Sliders, Steppers, Text fields, Toggles, Virtual keyboards + +### Status +Activity rings, Gauges, Progress indicators, Rating indicators + +### System Experiences +App Shortcuts, Complications, Controls, Live Activities, Notifications, Status bars, Top Shelf, Watch faces, Widgets + +## Modality + +### When to Use +- Deliver critical information requiring acknowledgment +- Confirm/modify a recent action +- Help people perform a distinct, narrowly scoped task +- Provide immersive experience or aid concentration + +### Best Practices +- Present modally only when there's a **clear benefit** +- Keep modal tasks **simple, short, and streamlined** +- Avoid hierarchy within modals — single path only +- Full-screen modal for in-depth content or complex tasks +- Always provide an **obvious dismiss mechanism** +- Confirm before closing if dismissal could lose user content +- Never stack modals — dismiss one before showing another +- Only one alert visible at a time + +## Searching + +### Best Practices +- If search is important, make it a **primary action** (tab bar, toolbar) +- Single search location — one clearly identified place +- Placeholder text to indicate searchable content +- Display current scope clearly +- Provide suggestions before and during typing +- Consider privacy — provide option to clear search history + +## Navigation Conventions +- Standard Back and Close buttons with system symbols +- Don't use text labels for Back/Close — use symbols +- Consistent implementation throughout the app diff --git a/references/hig-icons.md b/references/hig-icons.md new file mode 100644 index 0000000..c83674d --- /dev/null +++ b/references/hig-icons.md @@ -0,0 +1,91 @@ +# HIG: Icons & SF Symbols + +Source: [Apple HIG — App Icons](https://developer.apple.com/design/human-interface-guidelines/app-icons) | [Icons](https://developer.apple.com/design/human-interface-guidelines/icons) | [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) + +## App Icons + +### Layer Design +- iOS/iPadOS/macOS/watchOS: background + foreground layers with Liquid Glass effects +- tvOS: 2-5 layers for parallax +- visionOS: background + 1-2 layers as 3D object + +### Key Rules +- Embrace simplicity — simple icons are easiest to recognize +- Keep primary content centered to avoid masking truncation +- Prefer filled, overlapping shapes for depth +- Include text only when essential to brand +- Use illustrations, not photos or UI screenshots +- Let the system handle visual effects (highlights, shadows, bevels) + +### Specifications + +| Platform | Shape | Size | Appearances | +|----------|-------|------|-------------| +| iOS/iPadOS/macOS | Rounded rect | 1024x1024 px | Default, dark, clear, tinted | +| tvOS | Rounded rect | 800x480 px | N/A | +| visionOS | Circular | 1024x1024 px | N/A | +| watchOS | Circular | 1088x1088 px | N/A | + +## Interface Icons + +- Simple, recognizable, highly simplified designs +- Consistent size, detail, stroke weight, perspective across all icons +- Match icon weight to adjacent text weight +- Use vector format (PDF/SVG) — scales automatically +- Provide accessibility descriptions for custom icons + +## SF Symbols (6000+) + +### Rendering Modes + +| Mode | Description | +|------|-------------| +| **Monochrome** | One color for all layers | +| **Hierarchical** | One color, varying opacity per layer | +| **Palette** | Two or more colors, one per layer | +| **Multicolor** | Intrinsic colors (leaf=green, trash.slash=red) | + +### Gradients (SF Symbols 7+) +Linear gradient from single color, all rendering modes, best at larger sizes. + +### Variable Color +Represents changing values (0-100%): layers receive color at thresholds. +Use for **change**, NOT depth (use Hierarchical for depth). + +### Design Variants +- **Outline:** Text-like (toolbars, lists) +- **Fill:** Solid areas (tab bars, swipe actions, selection) +- **Slash:** Unavailability +- **Enclosed:** Circle/square (legibility at small sizes) + +System views auto-select variant (tab bar -> fill, toolbar -> outline). + +### Animations + +| Animation | Use For | +|-----------|---------| +| Appear/Disappear | Gradual show/hide | +| Bounce | Feedback that action occurred | +| Scale | Draw attention to selection | +| Pulse | Ongoing activity | +| Variable color | Progress, broadcasting | +| Replace/Magic Replace | Swap symbols with transitions | +| Wiggle | Highlight change or call to action | +| Breathe | Status changes, ongoing recording | +| Rotate | Progress indicators | +| Draw On/Off | Progress, direction (SF Symbols 7+) | + +### Common Standard Symbols + +| Action | Symbol | +|--------|--------| +| Add | `plus` | +| Delete | `trash` | +| Share | `square.and.arrow.up` | +| Search | `magnifyingglass` | +| Done | `checkmark` | +| Cancel | `xmark` | +| Compose | `square.and.pencil` | +| More | `ellipsis` | +| Filter | `line.3.horizontal.decrease` | +| Account | `person.crop.circle` | diff --git a/references/hig-layout.md b/references/hig-layout.md new file mode 100644 index 0000000..ea0b1d6 --- /dev/null +++ b/references/hig-layout.md @@ -0,0 +1,100 @@ +# HIG: Layout + +Source: [Apple HIG — Layout](https://developer.apple.com/design/human-interface-guidelines/layout) + +## Best Practices + +- Group related items using negative space, background shapes, colors, materials, or separators +- Give essential information sufficient space — don't crowd with nonessential details +- Extend content to fill screen/window edges — backgrounds and artwork should be full-bleed +- Scrollable layouts should continue to bottom and sides of device screen +- Controls (sidebars, tab bars) appear ON TOP of content, not on the same plane + +## Visual Hierarchy + +- Use Liquid Glass material for controls/navigation — distinct from content layer +- Use scroll edge effects (not backgrounds) to transition between content and control areas +- Place items in reading order (top-to-bottom, leading-to-trailing) — most important near top/leading +- Align components for easier scanning — alignment communicates organization +- Use progressive disclosure for hidden content (disclosure controls, partial item display) +- Provide enough space around controls — crowded controls are hard to distinguish + +## Adaptability + +Handle these variations: +- Different screen sizes, resolutions, color spaces +- Portrait/landscape orientations +- Dynamic Island, camera controls +- External displays, Display Zoom, resizable iPad windows +- Dynamic Type text-size changes +- RTL layout, internationalization + +Use SwiftUI layout or Auto Layout for adaptive interfaces. Respect safe areas, margins, and guides. + +## Guides & Safe Areas + +- **Layout guides:** Rectangular regions for positioning/aligning content +- **Safe areas:** Regions not covered by bars, Dynamic Island, camera housing +- Always respect safe areas — content outside feels wrong and may be hard to use + +## iOS + +- Support both portrait and landscape (or commit to one) +- Full-bleed game interfaces accommodating corner radius, sensor housing, Dynamic Island +- Avoid full-width buttons — respect system margins, match hardware curvature +- Keep status bar visible unless immersive experience + +## iPadOS + +- Windows freely resizable — account for full range of sizes +- Defer compact view as long as possible — hide tertiary columns first +- Test at common system sizes (halves, thirds, quadrants) +- Consider convertible tab bar (sidebar <-> tab bar) + +## visionOS + +- Center important content and controls in windows +- Keep content within window bounds (system controls are OUTSIDE bounds) +- Use ornaments for controls outside the window +- Space interactive components with centers at least 60pt apart + +## watchOS + +- Extend content edge-to-edge — bezel provides natural padding +- Max 3 glyph buttons or 2 text buttons side-by-side + +## Key Device Dimensions (Current Models) + +| Device | Points (portrait) | Pixels | Scale | +|--------|-------------------|--------|-------| +| iPhone 17 Pro Max | 440x956 | 1320x2868 | @3x | +| iPhone 17 Pro | 402x874 | 1206x2622 | @3x | +| iPhone Air | 420x912 | 1260x2736 | @3x | +| iPhone 16 Pro Max | 440x956 | 1320x2868 | @3x | +| iPhone 16 | 393x852 | 1179x2556 | @3x | +| iPhone SE | 375x667 | 750x1334 | @2x | +| iPad Pro 12.9" | 1024x1366 | 2048x2732 | @2x | +| iPad Pro 11" | 834x1194 | 1668x2388 | @2x | +| iPad Air 13" | 1024x1366 | 2048x2732 | @2x | +| iPad Air 11" | 820x1180 | 1640x2360 | @2x | +| iPad mini 8.3" | 744x1133 | 1488x2266 | @2x | + +## Size Classes + +| Device Type | Portrait | Landscape | +|-------------|----------|-----------| +| All iPads | Regular W, Regular H | Regular W, Regular H | +| iPhone Pro Max/Plus/Air | Compact W, Regular H | Regular W, Compact H | +| iPhone Pro/standard/mini | Compact W, Regular H | Compact W, Compact H | + +## tvOS Grid Spacing + +All grids: 40pt horizontal spacing, 100pt minimum vertical spacing. + +| Columns | Unfocused Content Width | +|---------|------------------------| +| 2 | 860 pt | +| 3 | 560 pt | +| 4 | 410 pt | +| 5 | 320 pt | +| 6 | 260 pt | diff --git a/references/hig-materials.md b/references/hig-materials.md new file mode 100644 index 0000000..63de9a8 --- /dev/null +++ b/references/hig-materials.md @@ -0,0 +1,82 @@ +# HIG: Materials + +Source: [Apple HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials) + +## Overview + +Two types of materials: +1. **Liquid Glass** — Dynamic material for controls/navigation (tab bars, sidebars, toolbars) +2. **Standard materials** — For visual differentiation within the content layer + +## Liquid Glass + +Forms a distinct functional layer floating above content. Content scrolls and peeks through. + +### Rules + +- **Don't** use Liquid Glass in the content layer — controls/navigation only +- Exception: transient interactive elements (sliders, toggles) take Liquid Glass when activated +- Use sparingly — system components get it automatically +- Only apply to custom controls for the most important functional elements + +### Variants + +| Variant | Appearance | Use When | +|---------|-----------|----------| +| **Regular** | Blurs + adjusts luminosity | Background might affect legibility; significant text (alerts, sidebars, popovers) | +| **Clear** | Highly translucent | Floating over media (photos, videos) for immersive experience | + +### Clear Variant Dimming + +- Bright underlying content: add dark dimming layer at 35% opacity +- Dark underlying content or AVKit controls: no dimming needed + +### Color on Liquid Glass + +- No inherent color — takes on colors from content behind it +- Apply color sparingly — reserve for primary actions (Done button accent) +- Color the background, not symbols/text +- Don't color multiple control backgrounds + +## Standard Materials + +### iOS/iPadOS + +Four levels (content layer only): ultra-thin, thin, regular (default), thick + +**Vibrancy for labels:** `label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel` +**Vibrancy for fills:** `fill`, `secondaryFill`, `tertiaryFill` + +Avoid `quaternaryLabel` on thin/ultraThin (too low contrast). + +### macOS + +- Several standard materials with designated purposes +- Two blending modes: **behind window** and **within window** + +### tvOS + +| Material | Recommended For | +|----------|----------------| +| ultraThin | Full-screen views, light scheme | +| thin | Overlays, light scheme | +| regular | General overlays | +| thick | Overlays, dark scheme | + +### visionOS + +- Windows use system **glass** material (unmodifiable, adaptive) +- No distinct Dark Mode — glass adapts to luminance behind it +- Prefer translucency over opaque colors +- Custom component materials: thin (interactive), regular (separations), thick (dark distinct) +- Vibrancy: `label`, `secondaryLabel`, `tertiaryLabel` + +### watchOS + +- Use materials for context in full-screen modal views +- Don't remove default material backgrounds from modal sheets + +## SwiftUI API + +- `.ultraThinMaterial`, `.thinMaterial`, `.regularMaterial`, `.thickMaterial`, `.ultraThickMaterial` +- Liquid Glass: `glassEffect(_:in:)` diff --git a/references/hig-motion.md b/references/hig-motion.md new file mode 100644 index 0000000..ba6f716 --- /dev/null +++ b/references/hig-motion.md @@ -0,0 +1,45 @@ +# HIG: Motion + +Source: [Apple HIG — Motion](https://developer.apple.com/design/human-interface-guidelines/motion) + +## Best Practices + +- Add motion **purposefully** — don't add for its own sake +- Make motion **optional** — never the only way to communicate information +- Supplement visual feedback with haptics and audio alternatives +- Liquid Glass responds differently to touch (more emphasis) vs trackpad (more subdued) + +## Feedback + +- Strive for **realistic** feedback following gestures and expectations +- Aim for **brevity and precision** — succinct animations convey info without distraction +- Avoid adding motion to **frequently used UI interactions** — system handles standard animations +- Let people **cancel motion** — don't force waiting for animations to complete +- Consider **animated SF Symbols** (SF Symbols 5+) + +## Accessibility + +- If `accessibilityReduceMotion` is enabled, replace large motion with **opacity crossfades** +- Non-negotiable for accessibility compliance + +## visionOS Motion + +- Avoid motion at edges of field of view — peripheral motion causes discomfort +- For large moving objects, increase translucency or lower contrast +- Use **fades** to relocate objects (fade out, move, fade in) +- Avoid letting people rotate virtual worlds — disrupts stability +- Provide a **stationary frame of reference** — contained movement is more comfortable +- Avoid sustained oscillation (especially ~0.2 Hz) + +## watchOS + +- SwiftUI provides streamlined motion APIs +- All layout/appearance animations include **built-in easing** (can't customize) + +## Design Principles + +1. Motion should **reinforce understanding** of how something works +2. **Brief and precise** over prominent and elaborate +3. Let system handle standard interaction animations +4. Custom animation for **unique moments** only (reveals, transitions, celebrations) +5. Always respect Reduce Motion accessibility setting diff --git a/references/hig-typography.md b/references/hig-typography.md new file mode 100644 index 0000000..3a8a55e --- /dev/null +++ b/references/hig-typography.md @@ -0,0 +1,111 @@ +# HIG: Typography + +Source: [Apple HIG — Typography](https://developer.apple.com/design/human-interface-guidelines/typography) + +## System Fonts + +- **San Francisco (SF):** SF Pro, SF Compact, SF Mono, SF Arabic, SF Armenian, SF Georgian, SF Hebrew — plus Rounded variants +- **New York (NY):** Serif family, works well alongside SF +- Variable font format with dynamic optical sizes — no need to pick discrete optical sizes + +## Default & Minimum Text Sizes + +| Platform | Default | Minimum | +|----------|---------|---------| +| 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 | + +## Text Styles (iOS/iPadOS — Large/Default) + +| Style | Weight | Size | Leading | Emphasized | +|-------|--------|------|---------|------------| +| Large Title | Regular | 34 pt | 41 pt | Bold | +| Title 1 | Regular | 28 pt | 34 pt | Bold | +| Title 2 | Regular | 22 pt | 28 pt | Bold | +| Title 3 | Regular | 20 pt | 25 pt | Semibold | +| Headline | Semibold | 17 pt | 22 pt | Semibold | +| Body | Regular | 17 pt | 22 pt | Semibold | +| Callout | Regular | 16 pt | 21 pt | Semibold | +| Subhead | Regular | 15 pt | 20 pt | Semibold | +| Footnote | Regular | 13 pt | 18 pt | Semibold | +| Caption 1 | Regular | 12 pt | 16 pt | Semibold | +| Caption 2 | Regular | 11 pt | 13 pt | Semibold | + +## macOS Text Styles + +| Style | Weight | Size | Line Height | Emphasized | +|-------|--------|------|-------------|------------| +| Large Title | Regular | 26 pt | 32 pt | Bold | +| Title 1 | Regular | 22 pt | 26 pt | Bold | +| Title 2 | Regular | 17 pt | 22 pt | Bold | +| Title 3 | Regular | 15 pt | 20 pt | Semibold | +| Headline | Bold | 13 pt | 16 pt | Heavy | +| Body | Regular | 13 pt | 16 pt | Semibold | +| Callout | Regular | 12 pt | 15 pt | Semibold | +| Subheadline | Regular | 11 pt | 14 pt | Semibold | +| Footnote | Regular | 10 pt | 13 pt | Semibold | +| Caption 1 | Regular | 10 pt | 13 pt | Medium | +| Caption 2 | Medium | 10 pt | 13 pt | Semibold | + +## tvOS Text Styles + +| Style | Weight | Size | Leading | Emphasized | +|-------|--------|------|---------|------------| +| Title 1 | Medium | 76 pt | 96 pt | Bold | +| Title 2 | Medium | 57 pt | 66 pt | Bold | +| Title 3 | Medium | 48 pt | 56 pt | Bold | +| Headline | Medium | 38 pt | 46 pt | Bold | +| Subtitle 1 | Regular | 38 pt | 46 pt | Medium | +| Callout | Medium | 31 pt | 38 pt | Bold | +| Body | Medium | 29 pt | 36 pt | Bold | +| Caption 1 | Medium | 25 pt | 32 pt | Bold | +| Caption 2 | Medium | 23 pt | 30 pt | Bold | + +## Best Practices + +- Avoid light font weights (Ultralight, Thin, Light) — prefer Regular, Medium, Semibold, Bold +- Minimize the number of typefaces — too many obscures hierarchy +- Use `bold()` in SwiftUI (not `fontWeight(.bold)`) so the system picks context-appropriate weight +- Use `Font.Design.default` for system font, `Font.Design.serif` for New York +- Don't embed system fonts — use the APIs + +## Dynamic Type + +- System-level feature in iOS, iPadOS, tvOS, visionOS, watchOS +- Text styles scale proportionately when people change text size +- Support Larger Accessibility Text Sizes (AX1-AX5 go up to 60pt body) +- Consider adjusting layout at large sizes (stack horizontally placed items vertically) +- Keep text truncation minimal — display as much useful text as possible +- Maintain consistent information hierarchy regardless of font size +- Use `isAccessibilityCategory` to detect when accessibility sizes are active + +## Custom Fonts + +- Always use `relativeTo:` with `.font(.custom())` to support Dynamic Type +- Use `@ScaledMetric` (iOS 18-) or `.font(.body.scaled(by:))` (iOS 26+) for custom sizing +- Implement accessibility features (Bold Text, Dynamic Type) for custom fonts + +## visionOS Specifics + +- Uses bolder body and title styles, plus Extra Large Title 1 and 2 +- Prefer 2D text — 3D text is harder to read +- Use billboarding for text associated with spatial objects +- Maximize contrast between text and container background + +## Tracking Values (SF Pro — Key Sizes) + +| Size | Tracking (pt) | +|------|--------------| +| 11 pt | +0.06 | +| 12 pt | 0.0 | +| 13 pt | -0.08 | +| 17 pt (body) | -0.43 | +| 22 pt | -0.26 | +| 28 pt | +0.38 | +| 34 pt | +0.40 | +| 48 pt | +0.35 | +| 72 pt | +0.14 | +| 96 pt | 0.0 |