LogWhispererAI/.opencode/skills/ui-ux-master/references/apple-platforms.md

Apple Platforms - Complete Guide

Comprehensive guide for all Apple platforms: iOS, iPadOS, macOS, watchOS, tvOS, and visionOS.

Table of Contents

1. Core Design Principles
2. Platform Comparison
3. Typography & SF Symbols
4. Color & Dark Mode
5. Layout Systems
6. Platform-Specific Deep Dives

---

1. Core Design Principles

Clarity

Definition: Content and functionality are obvious at every size

Implementation:

• Text legible at all Dynamic Type sizes
• Icons precise and immediately recognizable
• UI elements have clear affordances
• Adornments are subtle, never distracting

Deference

Definition: UI defers to content, never competing with it

Implementation:

• Content fills the screen
• Translucency hints at more content below
• Minimal bezels, gradients, shadows
• Controls appear only when needed

Depth

Definition: Visual layers and motion convey hierarchy

Implementation:

• Layered UI with elevation
• Smooth, realistic motion
• Touch interactions feel natural
• Spatial awareness in 3D (visionOS)

---

2. Platform Comparison

Platform	Screen	Input	Font	Key Pattern
iOS	4-7"	Touch	SF Pro	Tab Bar Navigation
iPadOS	10-13"	Touch + Pencil	SF Pro	Split View + Sidebar
macOS	13-32"	Mouse + Keyboard	SF Pro	Windows + Menu Bar
watchOS	1-2"	Digital Crown + Touch	SF Compact	Vertical Scroll
tvOS	TV	Siri Remote	SF Pro Display	Focus-Driven Grid
visionOS	Spatial	Eyes + Hands	SF Pro	3D Windows

When to Use Each Platform

iOS: Mobile apps, on-the-go tasks, touch-first interactions iPadOS: Creative tools, productivity, larger touch interfaces macOS: Professional tools, complex workflows, precision tasks watchOS: Glanceable info, quick actions, health tracking tvOS: Entertainment, casual browsing, living room visionOS: Spatial computing, immersive experiences, 3D content

---

3. Typography & SF Symbols

San Francisco Font Family

SF Pro: iOS, macOS, tvOS, visionOS

• Optimized for readability at all sizes
• Variable font weights (Ultralight to Black)
• Automatic optical sizing

SF Compact: watchOS

• Rounded, friendly appearance
• Optimized for small screens
• Slightly wider for legibility

SF Mono: Code and tabular data (all platforms)

• Fixed-width characters
• Clear distinction between similar characters (0/O, 1/l)

SF Arabic, SF Hebrew: Localized scripts

Dynamic Type

Text Styles (iOS/macOS):

Large Title - 34pt (iOS), 26pt (macOS)
Title 1     - 28pt (iOS), 22pt (macOS)
Title 2     - 22pt (iOS), 17pt (macOS)
Title 3     - 20pt (iOS), 15pt (macOS)
Headline    - 17pt (iOS), 13pt (macOS) bold
Body        - 17pt (iOS), 13pt (macOS)
Callout     - 16pt (iOS), 12pt (macOS)
Subheadline - 15pt (iOS), 11pt (macOS)
Footnote    - 13pt (iOS), 10pt (macOS)
Caption 1   - 12pt (iOS), 10pt (macOS)
Caption 2   - 11pt (iOS), 10pt (macOS)

Accessibility Sizes:

• Standard: -3 to +7 (12 sizes)
• Accessibility: AX1 to AX5 (5 additional sizes)
• Always test at largest sizes

SF Symbols

6,000+ icons designed by Apple:

• Match text weight automatically
• Variable color rendering modes
• Multicolor, hierarchical, palette, monochrome

Usage (SwiftUI):

Image(systemName: "star.fill")
Image(systemName: "heart.circle.fill")
  .symbolRenderingMode(.multicolor)

Best Practices:

• Match symbol weight to text weight
• Use filled variants for selected states
• Leverage multicolor for semantic meaning
• Custom symbols follow SF design

---

4. Color & Dark Mode

System Colors (Semantic)

Labels (Text):

• label - Primary text
• secondaryLabel - Secondary text
• tertiaryLabel - Tertiary text/disabled
• quaternaryLabel - Watermarks

Fills (Backgrounds):

• systemFill - Thin fill
• secondarySystemFill - Medium fill
• tertiarySystemFill - Thick fill
• quaternarySystemFill - Thickest fill

Backgrounds:

• systemBackground - Main background
• secondarySystemBackground - Grouped content
• tertiarySystemBackground - Grouped in grouped

Grouped Backgrounds:

• systemGroupedBackground
• secondarySystemGroupedBackground
• tertiarySystemGroupedBackground

Accent Colors

System Accent:

• Blue (default)
• User can change in Settings (iOS 14+)
• Use for interactive elements

Custom Accent:

• Define in Asset Catalog
• Adapts to light/dark automatically
• Use for brand identity

Dark Mode Strategy

Elevation, Not Brightness:

Base:       oklch(0.145 0 0)   (darkest)
Elevated:   oklch(0.205 0 0)   (slightly lighter)
Elevated 2: oklch(0.255 0 0)   (more elevated)

Avoid Pure Black:

• Use dark gray instead (#1C1C1E, not #000000)
• Provides subtle elevation
• Reduces eye strain on OLED

Test Both Modes:

• Design in both simultaneously
• Use semantic colors when possible
• Provide light/dark variants for images

---

5. Layout Systems

Safe Areas

iOS Safe Areas:

• Top: Status bar (44-59pt), notch, Dynamic Island
• Bottom: Home indicator (34pt)
• Leading/Trailing: 0pt (full bleed) to 20pt (margins)

SwiftUI:

.safeAreaInset(edge: .bottom) { /* toolbar */ }
.ignoresSafeArea() // when appropriate

UIKit:

view.safeAreaLayoutGuide
view.safeAreaInsets

Size Classes

iOS/iPadOS:

• Compact Width: iPhone portrait, iPhone landscape (smaller)
• Regular Width: iPad, iPhone landscape (larger models)
• Compact Height: iPhone landscape
• Regular Height: iPhone portrait, iPad

Adaptive Strategy:

• Compact → Single column, stack vertically
• Regular → Multi-column, sidebars, split views

SwiftUI:

@Environment(\.horizontalSizeClass) var horizontal
@Environment(\.verticalSizeClass) var vertical

Margins & Spacing

Standard Margins:

• iPhone: 16-20pt
• iPad: 20-24pt
• Mac: 20pt

Component Spacing:

• Tight: 4-8pt (related items)
• Standard: 12-16pt (grouped items)
• Loose: 20-32pt (sections)

Grid System:

• Base: 8pt grid
• Touch targets: 44×44pt minimum (iOS)
• macOS controls: 20pt height typical

---

6. Platform-Specific Deep Dives

iOS/iPadOS Patterns

See apple-ios.md for:

• Navigation patterns (Tab Bar, Navigation Bar, Sidebar)
• Lists, grids, and cards
• Forms and input
• Modality (sheets, alerts, popovers)
• Gestures and haptics
• Widgets and Live Activities

macOS Patterns

See apple-macos.md for:

• Windows and window management
• Sidebars and split views
• Toolbars and menu bar
• Keyboard shortcuts
• Drag and drop
• Preferences and settings

watchOS Patterns

See apple-watchos.md for:

• Glanceable design
• Digital Crown interaction
• Always-On Display
• Complications
• Notifications

---

Accessibility Across Platforms

VoiceOver (All Platforms)

• Descriptive labels for all interactive elements
• Logical focus order (top → bottom, left → right)
• Group related elements
• Announce dynamic changes

Dynamic Type (iOS/macOS)

• Support all text sizes (-3 to AX5)
• Test at largest accessibility sizes
• Allow multi-line labels
• Scale layouts appropriately

Keyboard Access (macOS/iPadOS)

• Full Keyboard Access in System Settings
• Tab order logical
• All actions keyboard-accessible
• Visible focus indicators

Reduce Motion (All Platforms)

• Provide crossfade alternative to slides
• Check UIAccessibility.isReduceMotionEnabled
• Essential animations only
• No auto-playing videos

Color & Contrast

• WCAG AA minimum (4.5:1 normal, 3:1 large)
• Test with grayscale
• Test with color blindness simulators
• Increase Contrast mode support

---

Platform Integration Features

iOS Features

• Widgets: Home Screen, Lock Screen, StandBy
• Live Activities: Dynamic Island, Lock Screen updates
• App Clips: Lightweight 10MB experiences
• Shortcuts: Siri Shortcuts, App Intents
• Handoff: Continue across devices
• SharePlay: Shared experiences

macOS Features

• Menu Bar: Global app menus
• Dock: App launcher with badges
• Finder Extensions: Custom sidebar items, actions
• Quick Look: Preview files with Space
• Spotlight: ⌘Space universal search
• Continuity: Handoff, Universal Clipboard, AirDrop

watchOS Features

• Complications: Watch face widgets
• Always-On Display: Simplified UI when down
• Workout APIs: Health and fitness integration
• Notifications: Short Look, Long Look

tvOS Features

• Top Shelf: Featured content on home screen
• Focus Engine: Automatic focus management
• Siri Integration: Voice control
• Game Controllers: Extended gamepad support

visionOS Features

• Spatial Windows: Float in 3D space
• Volumes: 3D content containers
• Immersion Dial: Environment blend control
• Spatial Audio: 3D positional audio
• Eye Tracking: Gaze-based targeting

---

Cross-Platform Development

SwiftUI (Recommended)

Advantages:

• Write once, deploy to all Apple platforms
• Automatic adaptations (size classes, input methods)
• Modern declarative syntax
• State management built-in

Best For:

• New projects
• Apps targeting iOS 14+
• Rapid prototyping
• Cross-platform apps

UIKit (iOS) / AppKit (macOS)

When to use:

• Fine-grained control needed
• Supporting older OS versions (< iOS 13)
• Complex custom UI
• Performance-critical apps

Platform-Specific Considerations

• Test on each platform's real devices
• Respect each platform's conventions
• Adapt navigation patterns appropriately
• Use platform-specific features when beneficial

---

Design Resources

Official:

• Apple HIG
• SF Symbols App
• Apple Design Resources

Tools:

• Sketch, Figma, Adobe XD (design)
• SF Pro font download (Apple)
• Color Contrast Analyzer
• Accessibility Inspector (Xcode)

Learning:

• WWDC Design sessions
• Apple Developer Forums
• Human Interface Guidelines documentation

---

For platform-specific patterns, see apple-ios.md, apple-macos.md, and apple-watchos.md