apple-human-interface-guidelines
Installation
SKILL.md
Apple Human Interface Guidelines
Comprehensive design reference covering all Apple platforms. Use this skill when:
- Designing or reviewing UI for any Apple platform
- Implementing SwiftUI or UIKit components following Apple conventions
- Making decisions about layout, typography, color, accessibility, or interaction patterns
- Integrating Apple technologies (Apple Pay, HealthKit, Game Center, etc.)
- Applying Apple's design principles to web or cross-platform development
How to Use This Skill
- Identify the task category (platform design, component, pattern, input, or technology)
- Find the matching reference below
- Load the specific reference file(s) needed
- For cross-cutting concerns (accessibility, color, typography), load the relevant foundations reference alongside any component reference
Quick Reference: Common Tasks
| Task | Load These References |
|---|---|
| Building a login/auth screen | foundations/privacy.md, technologies/sign-in-with-apple.md, patterns/managing-accounts.md |
| Designing a settings screen | patterns/patterns-settings.md, components/selection-and-input/toggles-guidelines.md |
| Choosing colors / dark mode | foundations/color-guidelines.md, foundations/dark-mode.md |
| Implementing navigation | components/navigation-and-search/tab-bars.md, components/navigation-and-search/sidebars.md, components/layout-and-organization/split-views.md |
| Typography / text sizing | foundations/typography-guidelines.md, foundations/writing-guidelines.md |
| Accessibility audit | foundations/accessibility.md, technologies/voiceover-guidelines.md |
| Designing a form | patterns/entering-data.md, components/selection-and-input/text-fields.md, components/selection-and-input/pickers.md |
| Building a list/table view | components/layout-and-organization/lists-and-tables.md, components/presentation/scroll-views.md |
| Adding search | patterns/searching-patterns.md, components/navigation-and-search/search-fields.md |
| Creating an app icon | foundations/app-icons.md |
| Designing notifications | patterns/managing-notifications.md, components/system-experiences/notifications-component.md |
| Building widgets | components/system-experiences/widgets-design-guidelines.md |
| Implementing payments | technologies/apple-pay.md, technologies/in-app-purchase.md |
| Designing charts/data viz | patterns/charting-data.md, components/content/components-charts.md |
| Building for visionOS | getting-started/designing-for-visionos.md, foundations/spatial-layout.md, foundations/immersive-experiences.md |
| Modal presentations | patterns/modality-guidelines.md, components/presentation/sheets-guidelines.md, components/presentation/alerts-component.md |
| Onboarding flow | patterns/onboarding.md, patterns/launching.md |
| Video/audio playback | patterns/playing-video.md, patterns/playing-audio.md |
| Game design | getting-started/designing-for-games.md, inputs/game-controls.md, technologies/game-center.md |
| RTL / internationalization | foundations/right-to-left.md, foundations/inclusion-guidelines.md |
| Sharing / collaboration | patterns/collaboration-and-sharing.md, components/menus-and-actions/activity-views.md |
| Generative AI features | technologies/generative-ai-guidelines.md, technologies/machine-learning-design.md |
1. Getting Started — Platform Design Fundamentals
Load these when starting design for a specific platform or needing platform constraints (screen sizes, input methods, ergonomics).
| Reference | When to Consult |
|---|---|
reference/getting-started/designing-for-ios.md |
iPhone app design: display characteristics, ergonomics, control placement, appearance adaptation |
reference/getting-started/designing-for-ipados.md |
iPad app design: large display, multitasking, multiple input modes, widgets |
reference/getting-started/designing-for-macos.md |
macOS app design: window management, menu bar, keyboard shortcuts, Dock |
reference/getting-started/designing-for-tvos.md |
tvOS/Apple TV: 8+ ft viewing, focus system, Siri Remote, cinematic presentation |
reference/getting-started/designing-for-visionos.md |
visionOS/Vision Pro: spatial design, immersion levels, eye/hand input, comfort |
reference/getting-started/designing-for-watchos.md |
watchOS: glanceable UI, Digital Crown, complications, Always On |
reference/getting-started/designing-for-games.md |
Game design across platforms: text sizes, controls, onboarding, accessibility |
2. Foundations — Cross-Cutting Design Principles
Core design principles applicable across platforms. Many of these apply to web and cross-platform development too.
Universally Applicable (any platform)
| Reference | When to Consult |
|---|---|
reference/foundations/accessibility.md |
Vision, hearing, mobility, speech, cognitive accessibility requirements and contrast ratios |
reference/foundations/color-guidelines.md |
Color choices, theming, contrast, system color specs, dark mode color values |
reference/foundations/dark-mode.md |
Dark mode implementation: adaptive colors, contrast (4.5:1 min), icon/image adaptation |
reference/foundations/typography-guidelines.md |
Font sizes, weights, leading, Dynamic Type specs, text styles per platform |
reference/foundations/writing-guidelines.md |
UX writing: voice/tone, button labels, error messages, capitalization |
reference/foundations/inclusion-guidelines.md |
Inclusive language, diverse representation, cultural sensitivity |
reference/foundations/layout-guidelines.md |
Visual hierarchy, adaptive layout, safe areas, device dimensions |
reference/foundations/motion-guidelines.md |
Animation best practices, accessibility, frame rates |
reference/foundations/privacy.md |
Permission flows, purpose strings, tracking rules, data protection |
reference/foundations/branding-guidelines.md |
Brand integration: accent colors, custom fonts, logos, content-first design |
Apple Platform–Specific
| Reference | When to Consult |
|---|---|
reference/foundations/app-icons.md |
App icon design: layers, shapes, sizes, dark/tinted, platform-specific specs |
reference/foundations/icons-guidelines.md |
Interface icons/glyphs, SF Symbol name mapping, macOS document icons |
reference/foundations/images-guidelines.md |
Image resolution, scale factors, file formats, tvOS layered images |
reference/foundations/sf-symbols.md |
SF Symbols: rendering modes, variable color, weights, animations, custom symbols |
reference/foundations/materials-guidelines.md |
Liquid Glass, vibrancy, material thickness, platform-specific materials |
reference/foundations/right-to-left.md |
RTL interfaces: text alignment, numeral handling, control/image flipping |
reference/foundations/spatial-layout.md |
visionOS: field of view, depth, 60pt min center-to-center spacing |
reference/foundations/immersive-experiences.md |
visionOS immersion: mixed/progressive/full, passthrough, comfort |
3. Patterns — Interaction & UX Patterns
Recurring UX patterns. Many are applicable beyond Apple platforms.
Data & Content
| Reference | When to Consult |
|---|---|
reference/patterns/charting-data.md |
Data visualization: chart simplicity, accessibility, chart type selection |
reference/patterns/entering-data.md |
Form design: validation, secure input, offering choices over text |
reference/patterns/searching-patterns.md |
Search: field placement, suggestions, privacy, Spotlight integration |
reference/patterns/file-management.md |
Document apps: auto-save, Quick Look, open/save dialogs |
Feedback & Status
| Reference | When to Consult |
|---|---|
reference/patterns/feedback-patterns.md |
Status, errors, task completion, warnings |
reference/patterns/loading-patterns.md |
Progress indicators, placeholder content, background downloads |
reference/patterns/playing-haptics.md |
Haptic feedback: predefined patterns, custom haptics |
Lifecycle & Navigation
| Reference | When to Consult |
|---|---|
reference/patterns/launching.md |
Launch screens (no text/branding), state restoration |
reference/patterns/onboarding.md |
First-run: interactive teaching, TipKit, permission timing |
reference/patterns/modality-guidelines.md |
Modal usage: when, dismiss conventions, avoiding stacked modals |
reference/patterns/going-full-screen.md |
Full-screen modes: layout, control visibility, gesture deferral |
reference/patterns/multitasking.md |
App switching, background tasks, multi-window |
Media
| Reference | When to Consult |
|---|---|
reference/patterns/playing-audio.md |
Audio categories, interruptions, Spatial Audio |
reference/patterns/playing-video.md |
Video playback: aspect ratio, PiP, system player, visionOS immersive video |
reference/patterns/live-viewing-apps.md |
Live TV/streaming: EPG, content footers, cloud DVR |
Social & Commerce
| Reference | When to Consult |
|---|---|
reference/patterns/collaboration-and-sharing.md |
Share button, collaboration popover, share sheet |
reference/patterns/managing-accounts.md |
Login flows, passkeys, biometrics, account deletion requirements |
reference/patterns/managing-notifications.md |
Interruption levels, Focus, marketing notification rules |
reference/patterns/ratings-and-reviews.md |
Rating prompts: timing, frequency, system prompt |
Utility
| Reference | When to Consult |
|---|---|
reference/patterns/drag-and-drop.md |
Drag & drop: move/copy, visual feedback, multi-item, accessibility |
reference/patterns/offering-help.md |
TipKit, tooltips (macOS/visionOS), contextual help |
reference/patterns/printing-pattern.md |
Print action placement, macOS print panel customization |
reference/patterns/undo-and-redo.md |
Undo/redo: multi-level, platform-specific shortcuts/gestures |
reference/patterns/patterns-settings.md |
Settings placement, defaults, macOS settings windows |
reference/patterns/workouts-pattern.md |
Fitness/workout UI: session screens, metrics, Activity rings |
4. Components — UI Building Blocks
Content
| Reference | When to Consult |
|---|---|
reference/components/content/components-charts.md |
Chart components: mark types, axes, color, interaction, accessibility |
reference/components/content/image-views.md |
Image display: overlays, animation, tvOS layered, visionOS spatial |
reference/components/content/text-views.md |
Multiline text views: when to use, legibility, editing |
reference/components/content/web-views.md |
Embedded web content: navigation, avoiding browser replication |
Layout & Organization
| Reference | When to Consult |
|---|---|
reference/components/layout-and-organization/components-boxes.md |
GroupBox/NSBox: grouping content, titles, nesting |
reference/components/layout-and-organization/collections-component.md |
Grid/row visual layouts: galleries, padding, dynamic changes |
reference/components/layout-and-organization/column-views.md |
macOS column (browser) views for deep hierarchies |
reference/components/layout-and-organization/disclosure-controls.md |
Disclosure triangles/buttons: expandable sections |
reference/components/layout-and-organization/components-labels.md |
Static labels: color hierarchy (primary→quaternary), legibility |
reference/components/layout-and-organization/lists-and-tables.md |
Lists/tables: styles, editing, selection, per-platform rules |
reference/components/layout-and-organization/lockups-tvos.md |
tvOS lockups: cards, posters, focus expansion |
reference/components/layout-and-organization/outline-views.md |
macOS outline views: hierarchical data, sorting, disclosure |
reference/components/layout-and-organization/split-views.md |
Multi-pane layouts: dividers, resizing, per-platform rules |
reference/components/layout-and-organization/tab-views.md |
Tabbed content panes: max tabs, labeling, alternatives |
Menus & Actions
| Reference | When to Consult |
|---|---|
reference/components/menus-and-actions/activity-views.md |
Share sheets: custom activities, icon sizing |
reference/components/menus-and-actions/buttons.md |
Button design: hit regions, styles, roles, per-platform types |
reference/components/menus-and-actions/context-menus.md |
Context menus: ordering, previews, destructive actions |
reference/components/menus-and-actions/dock-menus.md |
macOS Dock menus |
reference/components/menus-and-actions/edit-menus.md |
Edit menus: system vs custom, per-platform behavior |
reference/components/menus-and-actions/home-screen-quick-actions.md |
iOS/iPadOS long-press quick actions (4-action limit) |
reference/components/menus-and-actions/menus-design-guidelines.md |
Menu design: labeling, icons, grouping, submenus |
reference/components/menus-and-actions/ornaments-visionos.md |
visionOS ornaments: window-associated floating controls |
reference/components/menus-and-actions/pop-up-buttons.md |
Pop-up buttons: mutually exclusive option selection |
reference/components/menus-and-actions/pull-down-buttons.md |
Pull-down buttons: action menus, destructive actions |
reference/components/menus-and-actions/menu-bar-guidelines.md |
macOS/iPadOS menu bar: standard menus, required items, shortcuts |
reference/components/menus-and-actions/toolbars.md |
Toolbars: item grouping, overflow, navigation bars |
Navigation & Search
| Reference | When to Consult |
|---|---|
reference/components/navigation-and-search/path-controls.md |
macOS path controls: standard/pop-up styles |
reference/components/navigation-and-search/search-fields.md |
Search fields: placement, scope controls, tokens |
reference/components/navigation-and-search/sidebars.md |
Sidebars: hierarchy, hide/show, per-platform rules |
reference/components/navigation-and-search/tab-bars.md |
Tab bars: tab count, badges, Liquid Glass, sidebar adaptation |
reference/components/navigation-and-search/token-fields.md |
macOS token fields: text-to-token conversion |
Presentation
| Reference | When to Consult |
|---|---|
reference/components/presentation/action-sheets.md |
Action sheets: destructive buttons, Cancel, vs alerts/menus |
reference/components/presentation/alerts-component.md |
Alerts: titles, button placement, destructive styling |
reference/components/presentation/page-controls.md |
Page indicators: placement, interaction, customization |
reference/components/presentation/panels.md |
macOS panels/HUDs: floating supplementary windows |
reference/components/presentation/popovers.md |
Popovers: positioning, sizing, dismissal |
reference/components/presentation/scroll-views.md |
Scroll views: nesting, paging, edge effects, zoom |
reference/components/presentation/sheets-guidelines.md |
Sheets: detents, button placement, grabber, modal/nonmodal |
reference/components/presentation/windows-component.md |
Windows: types, states, visionOS volumes, glass backgrounds |
Selection & Input
| Reference | When to Consult |
|---|---|
reference/components/selection-and-input/color-wells.md |
Color picker/wells |
reference/components/selection-and-input/combo-boxes.md |
macOS combo boxes |
reference/components/selection-and-input/digit-entry-views.md |
tvOS PIN/digit entry |
reference/components/selection-and-input/image-wells.md |
macOS image wells (drag-and-drop image editing) |
reference/components/selection-and-input/pickers.md |
Pickers/date pickers: styles, modes, per-platform |
reference/components/selection-and-input/segmented-controls.md |
Segmented controls: modes, segment limits |
reference/components/selection-and-input/sliders.md |
Sliders: direction, tick marks, labels, circular (macOS) |
reference/components/selection-and-input/components-steppers.md |
Steppers: value visibility, pairing with text fields |
reference/components/selection-and-input/text-fields.md |
Text fields: sizing, placeholder, validation, keyboard types |
reference/components/selection-and-input/toggles-guidelines.md |
Toggles/switches/checkboxes/radio buttons |
reference/components/selection-and-input/virtual-keyboards.md |
Virtual keyboards: types, custom input views, extensions |
Status
| Reference | When to Consult |
|---|---|
reference/components/status/activity-rings.md |
Activity rings: colors, backgrounds, label RGB values |
reference/components/status/gauges.md |
Gauges/level indicators: styles, gradients |
reference/components/status/progress-indicators.md |
Progress bars, spinners, refresh controls |
reference/components/status/rating-indicators.md |
Star ratings (macOS only) |
System Experiences
| Reference | When to Consult |
|---|---|
reference/components/system-experiences/app-shortcuts.md |
App Shortcuts: Siri, Spotlight, voice interaction design |
reference/components/system-experiences/watchos-complications.md |
watchOS complications: families, image sizes, templates |
reference/components/system-experiences/controls-system-experience.md |
iOS Controls: Control Center, Lock Screen, Action button |
reference/components/system-experiences/live-activities.md |
Live Activities: anatomy, layout, dimensions per device |
reference/components/system-experiences/notifications-component.md |
Notification content, actions (4 max), badges, watchOS looks |
reference/components/system-experiences/status-bars.md |
iOS/iPadOS status bar: visibility, readability |
reference/components/system-experiences/top-shelf.md |
tvOS Top Shelf: templates, image dimensions |
reference/components/system-experiences/watch-faces.md |
watchOS watch faces: sharing, complications, previews |
reference/components/system-experiences/widgets-design-guidelines.md |
Widgets: families, sizes, rendering modes, exact dimensions |
5. Inputs — Interaction Methods
| Reference | When to Consult |
|---|---|
reference/inputs/action-button.md |
iPhone/Watch Action button: labeling (3-word max), behaviors |
reference/inputs/apple-pencil-and-scribble.md |
Apple Pencil: hover, double tap, squeeze, Scribble, PencilKit |
reference/inputs/camera-control.md |
iPhone 16 Camera Control: overlays, viewfinder layout |
reference/inputs/digital-crown.md |
Digital Crown: watchOS scrolling/navigation, visionOS system use |
reference/inputs/visionos-eyes-input.md |
visionOS gaze: hover effects, spacing (60pt centers), comfort |
reference/inputs/focus-and-selection.md |
Focus navigation: iPadOS, tvOS (5 states), visionOS |
reference/inputs/game-controls.md |
Game input: touch, game controllers, keyboard, visionOS spatial |
reference/inputs/gestures.md |
Gesture specs per platform, custom gestures, visionOS direct/indirect |
reference/inputs/gyro-and-accelerometer.md |
Motion sensing: permission copy, accessibility |
reference/inputs/keyboards-guidelines.md |
Physical keyboard shortcuts, modifier keys, Full Keyboard Access |
reference/inputs/nearby-interactions.md |
Ultra Wideband proximity/spatial awareness |
reference/inputs/pointing-devices.md |
Pointer/mouse/trackpad: effects, hit regions, magnetism |
reference/inputs/remotes-tvos.md |
Siri Remote: gestures, button behavior, focus integration |
6. Technologies — Platform Integrations
Payments & Commerce
| Reference | When to Consult |
|---|---|
reference/technologies/apple-pay.md |
Apple Pay: button types/styles/sizing, checkout, subscriptions |
reference/technologies/in-app-purchase.md |
IAP: subscription sign-up, offer codes, refunds, Family Sharing |
reference/technologies/tap-to-pay-on-iphone.md |
Tap to Pay: merchant flows, checkout UX, error handling |
Identity & Privacy
| Reference | When to Consult |
|---|---|
reference/technologies/sign-in-with-apple.md |
Sign in with Apple: button specs (min 140×30pt), custom buttons, UX flow |
reference/technologies/id-verifier.md |
ID Verifier: age/identity verification, data minimization |
reference/technologies/wallet-design-guidelines.md |
Wallet passes: styles, image specs, order tracking, identity |
Health & Fitness
| Reference | When to Consult |
|---|---|
reference/technologies/healthkit-guidelines.md |
HealthKit: privacy, Activity rings rules, Health icon usage |
reference/technologies/carekit.md |
CareKit: task views, charts, contacts, care plans |
reference/technologies/researchkit.md |
ResearchKit: onboarding flow order, surveys, active tasks |
Media & Communication
| Reference | When to Consult |
|---|---|
reference/technologies/airplay-guidelines.md |
AirPlay: streaming, mirroring, icon specs, terminology |
reference/technologies/shareplay.md |
SharePlay: activity sharing, visionOS Persona templates |
reference/technologies/live-photos.md |
Live Photos: frame adjustments, sharing, badges |
reference/technologies/shazamkit.md |
ShazamKit: mic privacy, iCloud opt-in |
reference/technologies/imessage-apps-and-stickers.md |
iMessage apps/stickers: views, icon/sticker sizes, formats |
AI & Machine Learning
| Reference | When to Consult |
|---|---|
reference/technologies/generative-ai-guidelines.md |
Gen AI: transparency, privacy, hallucination mitigation |
reference/technologies/machine-learning-design.md |
ML UX: feedback, calibration, confidence, corrections |
Platform Extensions
| Reference | When to Consult |
|---|---|
reference/technologies/app-clips.md |
App Clips: card specs, Code sizing, privacy constraints |
reference/technologies/mac-catalyst.md |
Mac Catalyst: iPad→Mac adaptation, idiom selection, navigation mapping |
reference/technologies/carplay-design-guidelines.md |
CarPlay: layout specs, icon sizes, audio behavior |
reference/technologies/siri-integration-guidelines.md |
Siri/Shortcuts: intents, voice UX, shortcut phrases, custom UI |
Accessibility
| Reference | When to Consult |
|---|---|
reference/technologies/voiceover-guidelines.md |
VoiceOver: alt labels, image descriptions, reading order, rotor |
Other Integrations
| Reference | When to Consult |
|---|---|
reference/technologies/always-on-display.md |
Always On: privacy redaction, dimming, layout consistency |
reference/technologies/augmented-reality.md |
AR/ARKit: object placement, coaching overlays, multiuser |
reference/technologies/game-center.md |
Game Center: access point, achievements, leaderboards, image specs |
reference/technologies/homekit-guidelines.md |
HomeKit: terminology, setup flows, Siri patterns, branding |
reference/technologies/icloud-guidelines.md |
iCloud: syncing, conflict resolution, storage, game saves |
reference/technologies/maps-guidelines.md |
MapKit: annotations, overlays, clustering, place cards |
reference/technologies/nfc-guidelines.md |
NFC: scanning UX, terminology, background tag reading |
reference/technologies/photo-editing-extensions.md |
Photo editing extensions: toolbar, previews, cancel confirmation |
Cross-Platform Applicability
These references contain principles useful beyond Apple platforms (web, Android, cross-platform):
- Accessibility (
foundations/accessibility.md,technologies/voiceover-guidelines.md) — contrast ratios, screen reader patterns, cognitive considerations - Color & Dark Mode (
foundations/color-guidelines.md,foundations/dark-mode.md) — theming, contrast, adaptive design - Typography (
foundations/typography-guidelines.md) — hierarchy, sizing, Dynamic Type concepts - Writing (
foundations/writing-guidelines.md) — UX copy, error messages, tone - Inclusion (
foundations/inclusion-guidelines.md) — inclusive language, representation - Privacy (
foundations/privacy.md) — permission patterns, data minimization - Motion (
foundations/motion-guidelines.md) — animation accessibility, reduced motion - Layout (
foundations/layout-guidelines.md) — responsive/adaptive patterns, visual hierarchy - Generative AI (
technologies/generative-ai-guidelines.md) — responsible AI design principles - ML Design (
technologies/machine-learning-design.md) — confidence display, correction patterns - Patterns — Most patterns (onboarding, feedback, loading, modality, search, settings, data entry) encode universal UX wisdom
Related skills
More from milistu/agent-skills
challenge-me
Direct technical advisor mode for counting/estimation and architecture/design
27pr-message
Write a concise, high-signal GitHub pull request message that explains intent, impact, and risk
25conventional-comments
Format review comments following the Conventional Comments standard. Use when writing code review comments, PR feedback, RFC reviews, peer reviews, or when the user asks for help with review comments.
23conventional-commits
Generate commit messages following the Conventional Commits v1.0.0 specification with Angular convention types. Use when creating git commits, writing commit messages, or when the user asks for help with commit messages.
23pr-review
Analyze and explain a pull request to help review it effectively
22humanizer
Detect and remove signs of AI-generated writing from text. Use whenever editing, rewriting, proofreading, or reviewing any text to make it sound more natural and human-written. Trigger this skill when the user asks to "humanize" text, remove AI patterns, make writing less robotic, sound more natural, avoid AI detection, rewrite in a human voice, de-slop text, or improve writing authenticity. Also use proactively when you notice AI writing patterns in text you're producing or editing.
14