claude-code-arcane 1.0.0

package/skills/ios-application-dev/references/swiftui-design-guidelines.md

@@ -0,0 +1,1167 @@
+# SwiftUI Design Guidelines
+
+Design rules based on Apple Human Interface Guidelines for building native iOS interfaces with SwiftUI.
+
+---
+
+## Design Philosophy
+
+iOS design prioritizes **content over chrome**. The interface should feel invisible—users focus on their tasks, not the UI.
+
+**Key mindsets:**
+
+1. **Let content breathe** — Use full-screen layouts, minimize borders and boxes, let images and text take center stage
+
+2. **Leverage system conventions** — Users already know how iOS works; don't reinvent navigation, gestures, or controls
+
+3. **Design for fingers** — Touch is imprecise; generous tap targets and forgiving gesture recognition matter more than pixel-perfect layouts
+
+4. **Respect user choices** — Honor Dynamic Type, Dark Mode, Reduce Motion, and other accessibility settings as first-class requirements
+
+**iOS 26+ Liquid Glass:**
+The latest iOS introduces translucent UI elements that respond to lighting and content behind them. Typography is bolder, text tends left-aligned for easier scanning.
+
+---
+
+## 1. Layout & Safe Areas
+
+**Impact:** CRITICAL
+
+### 1.1 Minimum 44pt Touch Targets
+
+All interactive elements must have minimum 44x44 **points** (not pixels—points scale with screen density).
+
+```swift
+Button(action: handleTap) {
+    Image(systemName: "heart.fill")
+}
+.frame(minWidth: 44, minHeight: 44)
+```
+
+Avoid placing critical interactions near screen edges where system gestures operate.
+
+### 1.2 Respect Safe Areas
+
+Never place interactive or essential content under the status bar, Dynamic Island, or home indicator. SwiftUI respects safe areas by default. Use `.ignoresSafeArea()` only for background fills, images, or decorative elements—never for text or interactive controls.
+
+```swift
+ZStack {
+    LinearGradient(colors: [.blue, .purple], startPoint: .top, endPoint: .bottom)
+        .ignoresSafeArea()
+    
+    VStack {
+        Text("Welcome")
+            .font(.largeTitle)
+        Button("Get Started") { }
+    }
+}
+```
+
+### 1.3 Primary Actions in Thumb Zone
+
+Place primary actions at the bottom of the screen where the user's thumb naturally rests. Secondary actions and navigation belong at the top.
+
+```swift
+VStack {
+    ScrollView {
+        // Content
+    }
+    
+    Spacer()
+    
+    Button("Submit") { submit() }
+        .buttonStyle(.borderedProminent)
+        .padding(.horizontal)
+        .padding(.bottom)
+}
+```
+
+### 1.4 Support All Screen Sizes
+
+Design for iPhone SE (375pt) through iPad Pro (1024pt+). Use Size Classes to adapt:
+
+```swift
+@Environment(\.horizontalSizeClass) private var sizeClass
+
+var body: some View {
+    if sizeClass == .compact {
+        VStack { content }
+    } else {
+        HStack { content }
+    }
+}
+```
+
+| Size Class | Devices |
+|------------|---------|
+| Compact width | iPhone portrait, small iPhone landscape |
+| Regular width | iPad, large iPhone landscape |
+
+Use flexible layouts, avoid hardcoded widths:
+
+```swift
+HStack(spacing: 16) {
+    ForEach(categories) { category in
+        CategoryCard(category: category)
+            .frame(maxWidth: .infinity)
+    }
+}
+```
+
+### 1.5 8pt Grid Alignment
+
+Align spacing, padding, and element sizes to multiples of 8 points (8, 16, 24, 32, 40, 48). Use 4pt for fine adjustments.
+
+### 1.6 Landscape Support
+
+Support landscape orientation unless the app is task-specific (e.g., camera). Use `ViewThatFits` or `GeometryReader` for adaptive layouts.
+
+```swift
+ViewThatFits {
+    HStack { contentViews }
+    VStack { contentViews }
+}
+```
+
+---
+
+## 2. Navigation
+
+**Impact:** CRITICAL
+
+### 2.1 Tab Bar for Top-Level Sections
+
+Use a tab bar at the bottom of the screen for 3 to 5 top-level sections. Each tab should represent a distinct category of content or functionality.
+
+```swift
+TabView(selection: $selectedTab) {
+    HomeView()
+        .tabItem {
+            Label("Home", systemImage: "house")
+        }
+        .tag(Tab.home)
+    
+    DiscoverView()
+        .tabItem {
+            Label("Discover", systemImage: "magnifyingglass")
+        }
+        .tag(Tab.discover)
+    
+    AccountView()
+        .tabItem {
+            Label("Account", systemImage: "person")
+        }
+        .tag(Tab.account)
+}
+```
+
+### 2.2 Navigation Architecture
+
+**Tab Bar (Flat)** — For 3-5 equal-importance sections
+- Always visible except when covered by modals
+- Each tab maintains its own navigation stack
+- Most important content leftmost (easier thumb access)
+
+**Hierarchical (Drill-Down)** — For tree-structured info
+- Push/pop navigation with back button
+- Minimize depth (3-4 levels max)
+- Provide search as escape hatch for deep trees
+
+**Modal (Focused Tasks)** — For self-contained workflows
+- Full-screen for critical tasks
+- Page sheet for dismissible tasks (swipe-down)
+- Clear Done/Cancel with confirmation if data loss possible
+
+Never use hamburger menus—they reduce feature discoverability significantly.
+
+### 2.3 Large Titles in Primary Views
+
+Use `.navigationBarTitleDisplayMode(.large)` for top-level views. Titles transition to inline when the user scrolls.
+
+```swift
+NavigationStack {
+    List(conversations) { conversation in
+        ConversationRow(conversation: conversation)
+    }
+    .navigationTitle("Inbox")
+    .navigationBarTitleDisplayMode(.large)
+}
+```
+
+### 2.4 Never Override Back Swipe
+
+The swipe-from-left-edge gesture for back navigation is a system-level expectation. Never attach custom gesture recognizers that interfere with it.
+
+### 2.5 Use NavigationStack for Hierarchical Content
+
+Use `NavigationStack` (not the deprecated `NavigationView`) for drill-down content. Use `NavigationPath` for programmatic navigation.
+
+```swift
+@State private var navPath = NavigationPath()
+
+NavigationStack(path: $navPath) {
+    List(products) { product in
+        NavigationLink(value: product) {
+            ProductRow(product: product)
+        }
+    }
+    .navigationDestination(for: Product.self) { product in
+        ProductDetailView(product: product)
+    }
+}
+```
+
+### 2.6 Preserve State Across Navigation
+
+When users navigate back and then forward, or switch tabs, restore the previous scroll position and input state.
+
+```swift
+@SceneStorage("selectedTab") private var selectedTab = Tab.home
+@SceneStorage("scrollPosition") private var scrollPosition: String?
+```
+
+---
+
+## 3. Typography & Dynamic Type
+
+**Impact:** HIGH
+
+### 3.1 Use Built-in Text Styles
+
+Always use semantic text styles—they scale with Dynamic Type automatically:
+
+| Style | Usage |
+|-------|-------|
+| `.largeTitle` | Screen titles |
+| `.title`, `.title2`, `.title3` | Section headers |
+| `.headline` | Emphasized body text |
+| `.body` | Primary content (17pt default) |
+| `.callout` | Secondary emphasized |
+| `.subheadline` | Supporting labels |
+| `.footnote`, `.caption` | Tertiary info |
+| `.caption2` | Minimum size (11pt) |
+
+```swift
+VStack(alignment: .leading, spacing: 8) {
+    Text("Article Title")
+        .font(.headline)
+    
+    Text("Published by Author Name")
+        .font(.subheadline)
+        .foregroundStyle(.secondary)
+    
+    Text(articleBody)
+        .font(.body)
+}
+```
+
+### 3.2 Support Dynamic Type Including Accessibility Sizes
+
+Dynamic Type can scale text up to approximately 200% at the largest accessibility sizes. Layouts must reflow—never truncate or clip essential text.
+
+```swift
+@Environment(\.dynamicTypeSize) private var typeSize
+
+var body: some View {
+    if typeSize.isAccessibilitySize {
+        VStack(alignment: .leading) { content }
+    } else {
+        HStack { content }
+    }
+}
+```
+
+### 3.3 Custom Fonts Must Scale
+
+If you use a custom typeface, scale it with `Font.custom(_:size:relativeTo:)` so it responds to Dynamic Type.
+
+```swift
+Text("Brand Text")
+    .font(.custom("Avenir-Medium", size: 17, relativeTo: .body))
+```
+
+### 3.4 SF Pro as System Font
+
+Use the system font (SF Pro) unless brand requirements dictate otherwise. SF Pro is optimized for legibility on Apple displays.
+
+### 3.5 Minimum 11pt Text
+
+Never display text smaller than 11pt. Prefer 17pt for body text. Use the `caption2` style (11pt) as the absolute minimum.
+
+### 3.6 Hierarchy Through Weight and Size
+
+Establish visual hierarchy through font weight and size. Do not rely solely on color to differentiate text levels.
+
+### 3.7 SF Symbols
+
+Use SF Symbols (6,900+ icons) instead of custom image assets:
+
+```swift
+// Basic usage with automatic text alignment
+Label("Favorites", systemImage: "star.fill")
+
+// Rendering modes
+Image(systemName: "cloud.sun.rain")
+    .symbolRenderingMode(.hierarchical)  // or .multicolor, .palette
+    .imageScale(.large)  // .small, .medium, .large
+```
+
+SF Symbols automatically match text weight, scale with Dynamic Type, and align to text baselines. Let them size naturally—don't force them into fixed-dimension containers.
+
+---
+
+## 4. Color & Dark Mode
+
+**Impact:** HIGH
+
+### 4.1 Use Semantic System Colors
+
+Never use hard-coded RGB, hex, or `.black`/`.white` directly. Use semantic colors:
+
+**Labels:**
+- `.primary`, `.secondary`, `.tertiary`, `.quaternary`
+
+**Backgrounds:**
+- `Color(.systemBackground)` — primary surface
+- `Color(.secondarySystemBackground)` — cards, grouped
+- `Color(.tertiarySystemBackground)` — nested elements
+
+**System Colors (adapt to appearance):**
+- `.blue`, `.red`, `.green`, `.orange`, `.yellow`, `.purple`, `.pink`, `.cyan`, `.mint`, `.teal`, `.indigo`, `.brown`, `.gray`
+
+```swift
+VStack {
+    Text("Primary content")
+        .foregroundStyle(.primary)
+    
+    Text("Supporting info")
+        .foregroundStyle(.secondary)
+}
+.background(Color(.systemBackground))
+```
+
+### 4.2 Custom Colors Need 4 Variants
+
+For custom colors, define in asset catalog with all appearance combinations:
+1. Light mode
+2. Dark mode
+3. Light mode + High Contrast
+4. Dark mode + High Contrast
+
+```swift
+Text("Branded element")
+    .foregroundStyle(Color("AccentBrand"))
+```
+
+For dynamic colors in code:
+
+```swift
+let dynamicColor = UIColor { traits in
+    traits.userInterfaceStyle == .dark 
+        ? UIColor(red: 0.9, green: 0.9, blue: 1.0, alpha: 1.0)
+        : UIColor(red: 0.1, green: 0.1, blue: 0.2, alpha: 1.0)
+}
+```
+
+### 4.3 Never Rely on Color Alone
+
+Always pair color with text, icons, or shapes to convey meaning. Approximately 8% of men have some form of color vision deficiency.
+
+```swift
+HStack(spacing: 6) {
+    Image(systemName: "exclamationmark.triangle.fill")
+    Text("Connection failed")
+}
+.foregroundStyle(.red)
+```
+
+### 4.4 4.5:1 Contrast Ratio Minimum
+
+All text must meet WCAG AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt+ bold).
+
+### 4.5 Support Display P3 Wide Gamut
+
+Use Display P3 color space for vibrant, accurate colors on modern iPhones. Define colors in the asset catalog with the Display P3 gamut.
+
+### 4.6 Background Hierarchy
+
+Layer backgrounds to create visual depth:
+
+```swift
+// Level 1: Main view background
+Color(.systemBackground)
+
+// Level 2: Cards, grouped sections
+Color(.secondarySystemBackground)
+
+// Level 3: Nested elements within cards
+Color(.tertiarySystemBackground)
+```
+
+### 4.7 One Accent Color for Interactive Elements
+
+Choose a single tint/accent color for all interactive elements (buttons, links, toggles). This creates a consistent, learnable visual language.
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .tint(.orange)
+        }
+    }
+}
+```
+
+---
+
+## 5. Accessibility
+
+**Impact:** CRITICAL
+
+### 5.1 VoiceOver Labels on All Interactive Elements
+
+Every button, control, and interactive element must have a meaningful accessibility label.
+
+```swift
+Button(action: toggleFavorite) {
+    Image(systemName: isFavorite ? "heart.fill" : "heart")
+}
+.accessibilityLabel(isFavorite ? "Remove from favorites" : "Add to favorites")
+```
+
+### 5.2 Logical VoiceOver Navigation Order
+
+Ensure VoiceOver reads elements in a logical order. Use `.accessibilitySortPriority()` to adjust when the visual layout doesn't match the reading order.
+
+```swift
+HStack {
+    Text("$49.99")
+        .accessibilitySortPriority(2)
+    Text("Premium Plan")
+        .accessibilitySortPriority(1)
+}
+```
+
+### 5.3 Support Bold Text
+
+When the user enables Bold Text in Settings, SwiftUI text styles handle this automatically. Custom text must respond to `UIAccessibility.isBoldTextEnabled`.
+
+### 5.4 Support Reduce Motion
+
+Disable decorative animations and parallax when Reduce Motion is enabled.
+
+```swift
+@Environment(\.accessibilityReduceMotion) private var reduceMotion
+
+var body: some View {
+    CardView()
+        .animation(reduceMotion ? nil : .spring(duration: 0.4), value: expanded)
+}
+```
+
+### 5.5 Support Increase Contrast
+
+When the user enables Increase Contrast, ensure custom colors have higher-contrast variants. Use `@Environment(\.colorSchemeContrast)` to detect.
+
+### 5.6 Don't Convey Info Only by Color, Shape, or Position
+
+Information must be available through multiple channels. Pair visual indicators with text or accessibility descriptions.
+
+### 5.7 Alternative Interactions for All Gestures
+
+Every custom gesture must have an equivalent tap-based or menu-based alternative for users who cannot perform complex gestures.
+
+### 5.8 Support Switch Control and Full Keyboard Access
+
+Ensure all interactions work with Switch Control (external switches) and Full Keyboard Access (Bluetooth keyboards). Test navigation order and focus behavior.
+
+---
+
+## 6. Gestures & Input
+
+**Impact:** HIGH
+
+### 6.1 Use Standard Gestures
+
+Stick to gestures users already know:
+
+- **Tap** — Select items, trigger buttons
+- **Long press** — Show context menus, enter edit mode
+- **Horizontal swipe** — List row actions (delete/archive), back navigation
+- **Vertical swipe** — Scroll content, dismiss sheets
+- **Pinch** — Scale images/maps
+- **Rotate** — Adjust angle (photos, maps)
+
+### 6.2 Never Override System Gestures
+
+iOS reserves these edge gestures—do not intercept:
+
+- Left edge swipe → back navigation
+- Top-left pull → Notification Center
+- Top-right pull → Control Center
+- Bottom edge swipe → home/app switcher
+
+### 6.3 Custom Gestures Must Be Discoverable
+
+If you add a custom gesture, provide visual hints (e.g., a grabber handle) and ensure the action is also available through a visible button or menu item.
+
+### 6.4 Support All Input Methods
+
+Design for touch first, but also support hardware keyboards, assistive devices (Switch Control, head tracking), and pointer input.
+
+---
+
+## 7. Components
+
+**Impact:** HIGH
+
+### 7.1 Button Styles
+
+Use the built-in button styles appropriately:
+
+```swift
+VStack(spacing: 16) {
+    Button("Checkout") { checkout() }
+        .buttonStyle(.borderedProminent)
+    
+    Button("Add to Wishlist") { addToWishlist() }
+        .buttonStyle(.bordered)
+    
+    Button("Remove Item", role: .destructive) { removeItem() }
+}
+```
+
+### 7.2 Alerts — Critical Info Only
+
+Use alerts sparingly for critical information that requires a decision. Prefer 2 buttons; maximum 3.
+
+```swift
+.alert("Discard Draft?", isPresented: $showDiscardAlert) {
+    Button("Discard", role: .destructive) { discardDraft() }
+    Button("Keep Editing", role: .cancel) { }
+} message: {
+    Text("Your unsaved changes will be lost.")
+}
+```
+
+### 7.3 Sheets for Scoped Tasks
+
+Present sheets for self-contained tasks. Always provide a way to dismiss (close button or swipe down).
+
+```swift
+.sheet(isPresented: $showEditor) {
+    NavigationStack {
+        EditorView()
+            .navigationTitle("Edit Profile")
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("Cancel") { showEditor = false }
+                }
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Save") { saveProfile() }
+                }
+            }
+    }
+    .presentationDetents([.medium, .large])
+    .presentationDragIndicator(.visible)
+}
+```
+
+### 7.4 Lists — The Foundation of iOS Apps
+
+Most iOS apps are lists ("90% of mobile design is list design").
+
+**List Styles:**
+- `.insetGrouped` — Modern default (rounded corners, margins)
+- `.grouped` — Traditional grouped sections
+- `.plain` — Edge-to-edge rows
+- `.sidebar` — Three-column iPad layout
+
+**Swipe Actions:**
+- Leading swipe → Positive actions (mark read, archive)
+- Trailing swipe → Destructive actions (delete at far right)
+- Maximum 3-4 actions per side
+
+**Row Accessories:**
+- Chevron → Indicates navigation
+- Checkmark → Shows selection
+- Detail button → Additional info without navigation
+
+```swift
+List {
+    Section("Notifications") {
+        ForEach(notifications) { notification in
+            NotificationRow(notification: notification)
+                .swipeActions(edge: .trailing, allowsFullSwipe: true) {
+                    Button(role: .destructive) {
+                        delete(notification)
+                    } label: {
+                        Label("Delete", systemImage: "trash")
+                    }
+                    
+                    Button {
+                        markRead(notification)
+                    } label: {
+                        Label("Read", systemImage: "envelope.open")
+                    }
+                    .tint(.blue)
+                }
+                .swipeActions(edge: .leading) {
+                    Button {
+                        pin(notification)
+                    } label: {
+                        Label("Pin", systemImage: "pin")
+                    }
+                    .tint(.orange)
+                }
+        }
+    }
+}
+.listStyle(.insetGrouped)
+```
+
+### 7.5 Tab Bar Behavior
+
+- Use SF Symbols for tab icons — filled variant for the selected tab, outline for unselected
+- Never hide the tab bar when navigating deeper within a tab
+- Badge important counts with `.badge()`
+
+```swift
+NotificationsView()
+    .tabItem {
+        Label("Notifications", systemImage: "bell")
+    }
+    .badge(unreadCount)
+```
+
+### 7.6 Search
+
+Place search using `.searchable()`. Provide search suggestions and support recent searches.
+
+```swift
+NavigationStack {
+    List(searchResults) { item in
+        ItemRow(item: item)
+    }
+    .searchable(text: $query, prompt: "Search products")
+    .searchSuggestions {
+        ForEach(recentSearches, id: \.self) { term in
+            Text(term)
+                .searchCompletion(term)
+        }
+    }
+}
+```
+
+### 7.7 Context Menus
+
+Use context menus (long press) for secondary actions. Never use a context menu as the only way to access an action.
+
+```swift
+ImageThumbnail(image: image)
+    .contextMenu {
+        Button { shareImage(image) } label: {
+            Label("Share", systemImage: "square.and.arrow.up")
+        }
+        Button { copyImage(image) } label: {
+            Label("Copy", systemImage: "doc.on.doc")
+        }
+        Divider()
+        Button(role: .destructive) { deleteImage(image) } label: {
+            Label("Delete", systemImage: "trash")
+        }
+    }
+```
+
+### 7.8 Forms and Input
+
+**Text Fields:**
+- 44pt minimum height
+- Match keyboard type to input (`.emailAddress`, `.numberPad`, `.URL`)
+- Clear button when text entered
+- Placeholder uses `.quaternary` label color
+
+```swift
+Form {
+    Section("Account") {
+        TextField("Email", text: $email)
+            .textContentType(.emailAddress)
+            .keyboardType(.emailAddress)
+            .autocapitalization(.none)
+        
+        SecureField("Password", text: $password)
+            .textContentType(.password)
+    }
+    
+    Section {
+        Button("Sign In") { signIn() }
+            .disabled(email.isEmpty || password.isEmpty)
+    }
+}
+```
+
+**Pickers:**
+- Inline → 3-7 options
+- Menu → 2-5 options (iOS 14+)
+- Wheel → Date/time or long lists
+
+### 7.9 Progress Indicators
+
+- Determinate `ProgressView(value:total:)` for operations with known duration
+- Indeterminate `ProgressView()` for unknown duration
+- Never block the entire screen with a spinner
+
+```swift
+VStack {
+    ProgressView(value: uploadProgress, total: 1.0)
+        .progressViewStyle(.linear)
+    
+    Text("\(Int(uploadProgress * 100))% uploaded")
+        .font(.caption)
+        .foregroundStyle(.secondary)
+}
+```
+
+---
+
+## 8. Patterns
+
+**Impact:** MEDIUM
+
+### 8.1 Onboarding — Max 3 Pages, Skippable
+
+Keep onboarding to 3 or fewer pages. Always provide a skip option. Defer sign-in until the user needs authenticated features.
+
+```swift
+TabView(selection: $currentPage) {
+    OnboardingPage(icon: "sparkles", title: "Smart Features", description: "...")
+        .tag(0)
+    OnboardingPage(icon: "bell.badge", title: "Stay Notified", description: "...")
+        .tag(1)
+    OnboardingPage(icon: "lock.shield", title: "Private & Secure", description: "...")
+        .tag(2)
+}
+.tabViewStyle(.page)
+.overlay(alignment: .topTrailing) {
+    Button("Skip") { finishOnboarding() }
+        .padding()
+}
+```
+
+### 8.2 Loading — Skeleton Views, No Blocking Spinners
+
+Use skeleton/placeholder views that match the layout of the content being loaded. Never show a full-screen blocking spinner.
+
+```swift
+if isLoading {
+    ForEach(0..<5, id: \.self) { _ in
+        ArticleRowPlaceholder()
+            .redacted(reason: .placeholder)
+    }
+} else {
+    ForEach(articles) { article in
+        ArticleRow(article: article)
+    }
+}
+```
+
+### 8.3 Launch Screen — Match First Screen
+
+The launch storyboard must visually match the initial screen of the app. No splash logos, no branding screens. This creates the perception of instant launch.
+
+### 8.4 Modality — Use Sparingly
+
+Present modal views only when the user must complete or abandon a focused task. Always provide a clear dismiss action. Never stack modals on top of modals.
+
+### 8.5 Notifications — High Value Only
+
+Only send notifications for content the user genuinely cares about. Support actionable notifications. Categorize notifications so users can control them granularly.
+
+### 8.6 Settings Placement
+
+- Frequent settings: In-app settings screen accessible from a profile or gear icon
+- Privacy/permission settings: Defer to the system Settings app via URL scheme
+- Never duplicate system-level controls in-app
+
+### 8.7 Action Sheets
+
+For destructive or multiple-choice actions:
+
+```swift
+.confirmationDialog("Delete Photo?", isPresented: $showDelete, titleVisibility: .visible) {
+    Button("Delete", role: .destructive) { deletePhoto() }
+    Button("Cancel", role: .cancel) { }
+} message: {
+    Text("This action cannot be undone.")
+}
+```
+
+- Destructive action at top (red)
+- Cancel at bottom
+- Dismiss by tapping outside
+
+### 8.8 Pull-to-Refresh
+
+Standard pattern for content updates:
+
+```swift
+List(items) { item in
+    ItemRow(item: item)
+}
+.refreshable {
+    await loadNewItems()
+}
+```
+
+### 8.9 Haptic Feedback
+
+Provide tactile response for significant actions:
+
+| Generator | Usage |
+|-----------|-------|
+| `UIImpactFeedbackGenerator` | Physical impacts (.light, .medium, .heavy) |
+| `UINotificationFeedbackGenerator` | Success, warning, error |
+| `UISelectionFeedbackGenerator` | Selection changes |
+
+```swift
+Button("Complete") {
+    let feedback = UINotificationFeedbackGenerator()
+    feedback.notificationOccurred(.success)
+    markComplete()
+}
+```
+
+---
+
+## 9. Privacy & Permissions
+
+**Impact:** HIGH
+
+### 9.1 Request Permissions in Context
+
+Request a permission at the moment the user takes an action that needs it—never at app launch.
+
+```swift
+Button("Take Photo") {
+    AVCaptureDevice.requestAccess(for: .video) { granted in
+        if granted {
+            showCamera = true
+        }
+    }
+}
+```
+
+### 9.2 Explain Before System Prompt
+
+Show a custom explanation screen before triggering the system permission dialog. The system dialog only appears once—if the user denies, the app must direct them to Settings.
+
+```swift
+struct LocationPermissionView: View {
+    var body: some View {
+        VStack(spacing: 20) {
+            Image(systemName: "location.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.blue)
+            
+            Text("Find Nearby Places")
+                .font(.title2.bold())
+            
+            Text("We use your location to show relevant results. Your location is never stored or shared.")
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+            
+            Button("Enable Location") {
+                locationManager.requestWhenInUseAuthorization()
+            }
+            .buttonStyle(.borderedProminent)
+            
+            Button("Not Now") { dismiss() }
+                .foregroundStyle(.secondary)
+        }
+        .padding()
+    }
+}
+```
+
+### 9.3 Support Sign in with Apple
+
+If the app offers any third-party sign-in (Google, Facebook), it must also offer Sign in with Apple. Present it as the first option.
+
+### 9.4 Don't Require Accounts Unless Necessary
+
+Let users explore the app before requiring sign-in. Gate only features that genuinely need authentication (purchases, sync, social features).
+
+### 9.5 App Tracking Transparency
+
+If you track users across apps or websites, display the ATT prompt. Respect denial—do not degrade the experience for users who opt out.
+
+### 9.6 Location Button for One-Time Access
+
+Use `LocationButton` for actions that need location once without requesting ongoing permission.
+
+```swift
+LocationButton(.currentLocation) {
+    fetchNearbyResults()
+}
+.symbolVariant(.fill)
+.labelStyle(.titleAndIcon)
+```
+
+---
+
+## 10. System Integration
+
+**Impact:** MEDIUM
+
+### 10.1 Widgets for Glanceable Data
+
+Provide widgets using WidgetKit for information users check frequently. Widgets are not interactive (beyond tapping to open the app), so show the most useful snapshot.
+
+### 10.2 App Shortcuts for Key Actions
+
+Define App Shortcuts so users can trigger key actions from Siri, Spotlight, and the Shortcuts app.
+
+```swift
+struct MyAppShortcuts: AppShortcutsProvider {
+    static var appShortcuts: [AppShortcut] {
+        AppShortcut(
+            intent: QuickAddIntent(),
+            phrases: ["Add item in \(.applicationName)"],
+            shortTitle: "Quick Add",
+            systemImageName: "plus.circle"
+        )
+    }
+}
+```
+
+### 10.3 Spotlight Indexing
+
+Index app content with `CSSearchableItem` so users can find it from Spotlight search.
+
+### 10.4 Share Sheet Integration
+
+Support the system share sheet for content that users might want to send elsewhere.
+
+```swift
+ShareLink(item: article.url, subject: Text(article.title)) {
+    Label("Share Article", systemImage: "square.and.arrow.up")
+}
+```
+
+### 10.5 Live Activities
+
+Use Live Activities and the Dynamic Island for real-time, time-bound events (delivery tracking, sports scores, workouts).
+
+### 10.6 Handle Interruptions Gracefully
+
+Save state and pause gracefully when interrupted by phone calls, Siri invocations, notifications, app switcher, or FaceTime SharePlay.
+
+```swift
+@Environment(\.scenePhase) private var scenePhase
+
+var body: some View {
+    ContentView()
+        .onChange(of: scenePhase) { _, newPhase in
+            switch newPhase {
+            case .active:
+                resumeActivity()
+            case .inactive:
+                pauseActivity()
+            case .background:
+                saveState()
+            @unknown default:
+                break
+            }
+        }
+}
+```
+
+---
+
+## Quick Reference
+
+### Navigation & Structure
+
+| Component | When to Use |
+|-----------|-------------|
+| `TabView` | 3-5 main app sections |
+| `NavigationStack` | Hierarchical content drill-down |
+| `.sheet` | Focused tasks requiring user completion |
+| `.alert` | Decisions that block workflow |
+| `.contextMenu` | Additional actions (always provide alternatives) |
+
+### Data Display
+
+| Component | When to Use |
+|-----------|-------------|
+| `List` | Scrollable rows with sections |
+| `LazyVGrid` / `LazyHGrid` | Grid layouts |
+| `.searchable` | Filterable content |
+| `ProgressView` | Loading or task progress |
+
+### User Input
+
+| Component | When to Use |
+|-----------|-------------|
+| `TextField` | Single-line text |
+| `TextEditor` | Multi-line text |
+| `Picker` | Selection from options |
+| `Toggle` | Binary on/off choice |
+| `Stepper` | Numeric increment/decrement |
+
+### System Features
+
+| Component | When to Use |
+|-----------|-------------|
+| `ShareLink` | Content sharing |
+| `LocationButton` | One-time location access |
+| `PhotosPicker` | Image selection |
+| `UIImpactFeedbackGenerator` | Tactile response |
+
+---
+
+## Anti-Patterns
+
+Avoid these common HIG violations:
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Hamburger/drawer menu | Hides navigation, users miss features | Use TabView with 3-5 tabs |
+| Broken back swipe | Custom gestures block system navigation | Keep NavigationStack default behavior |
+| Full-screen spinner | App feels frozen, no progress indication | Use skeleton views with `.redacted()` |
+| Logo splash screen | Artificial delay, wastes user time | Match launch screen to first view |
+| Permissions at launch | Users deny without context | Request when action requires it |
+| Fixed font sizes | Breaks Dynamic Type, accessibility issues | Use `.font(.body)` semantic styles |
+| Color-only status | Colorblind users miss information | Add icons or text labels |
+| Alert overuse | Interrupts flow for minor info | Use inline messages or banners |
+| Hidden tab bar | Users lose navigation context | Keep tab bar visible on push |
+| Content in unsafe areas | Text hidden under notch/Dynamic Island | Only ignore safe area for backgrounds |
+| No modal dismiss | Users trapped in view | Add cancel button and swipe dismiss |
+| Gesture-only actions | Accessibility users blocked | Provide button/menu alternatives |
+| Small tap targets | Frequent mis-taps | Minimum 44x44pt hit area |
+| Nested modals | Navigation confusion | Use NavigationStack within single sheet |
+| Hardcoded colors | Broken in Dark Mode | Use semantic colors or asset variants |
+
+---
+
+## Review Checklist
+
+Code review checklist for SwiftUI apps:
+
+### Layout
+- [ ] Interactive elements have 44pt minimum touch area
+- [ ] Essential content stays within safe area bounds
+- [ ] Main actions positioned for one-handed use (bottom)
+- [ ] UI works across iPhone SE to Pro Max screen sizes
+- [ ] Spacing uses 8pt increments
+
+### Navigation
+- [ ] Main sections use bottom TabView (3-5 tabs)
+- [ ] No drawer/hamburger navigation
+- [ ] Root views show large navigation titles
+- [ ] System back gesture not blocked
+- [ ] Tab state persists when switching
+
+### Text & Fonts
+- [ ] Text uses semantic styles (`.body`, `.headline`, etc.)
+- [ ] Dynamic Type works at all sizes including accessibility
+- [ ] Content reflows without truncation at large sizes
+- [ ] No text below 11pt
+
+### Colors
+- [ ] Uses `.primary`, `.secondary`, `Color(.systemBackground)`
+- [ ] Custom colors have light/dark variants in assets
+- [ ] Status indicators combine color with icon/text
+- [ ] Text contrast ratio meets WCAG AA
+
+### Accessibility
+- [ ] Icon buttons have `.accessibilityLabel()`
+- [ ] VoiceOver order matches logical flow
+- [ ] Animations respect `accessibilityReduceMotion`
+- [ ] All actions have non-gesture alternatives
+
+### Modals & Alerts
+- [ ] Alerts reserved for critical decisions only
+- [ ] Sheets provide clear dismiss mechanism
+- [ ] No stacked modal presentations
+
+### Permissions
+- [ ] Permissions requested at point of use
+- [ ] Pre-permission explanation screens used
+- [ ] Core features work without sign-in
+
+---
+
+## iPad Adaptation
+
+iPad users expect different interaction patterns:
+
+**Layout:** Use `NavigationSplitView` for master-detail:
+
+```swift
+NavigationSplitView(columnVisibility: $columnVisibility) {
+    SidebarView()
+} content: {
+    ListContentView()
+} detail: {
+    DetailView()
+}
+.navigationSplitViewStyle(.balanced)
+```
+
+**Presentation:** Action sheets become popovers automatically, but you can force popover:
+
+```swift
+.popover(isPresented: $showOptions) {
+    OptionsView()
+}
+```
+
+**Keyboard:** Add shortcuts for power users:
+
+```swift
+.keyboardShortcut("n", modifiers: .command)  // Cmd+N
+```
+
+**Drag & Drop:** Enable cross-app data transfer:
+
+```swift
+.draggable(item)
+.dropDestination(for: Item.self) { items, location in
+    handleDrop(items)
+    return true
+}
+```
+
+---
+
+## Pre-Release Verification
+
+Run through these scenarios before shipping:
+
+**Visual consistency:**
+- Switch between Light/Dark mode—does everything remain readable?
+- Crank Dynamic Type to maximum—does layout adapt or break?
+- Enable Bold Text—do custom fonts respond?
+
+**Interaction quality:**
+- Can you complete every action using only VoiceOver?
+- Do all buttons feel tappable on first try (no mis-taps)?
+- Does back-swipe work everywhere in navigation?
+
+**Edge cases:**
+- What happens on iPhone SE's small screen?
+- What happens on iPad with keyboard attached?
+- What shows when network fails mid-operation?
+- What happens if user denies permissions?
+
+**Platform compliance:**
+- Are you using SF Symbols instead of custom icon PNGs?
+- Are all colors from semantic palette or asset catalog with variants?
+- Do destructive actions require explicit confirmation?
+
+---
+
+*SwiftUI, SF Symbols, Dynamic Island, and Apple are trademarks of Apple Inc.*