buildanything 1.7.0 → 1.8.0

package/skills/ios/ios-hig/references/interaction.md

@@ -0,0 +1,199 @@
+# Interaction
+
+Apple Human Interface Guidelines for touch targets, input, navigation, layout, and hierarchy.
+
+## Table of Contents
+1. [Touch Targets and Input](#touch-targets-and-input)
+2. [Navigation and Flows](#navigation-and-flows)
+3. [Layout, Hierarchy, and Grouping](#layout-hierarchy-and-grouping)
+
+## Touch Targets and Input
+
+### Critical Rules
+
+- Use system controls (`Button`, `Toggle`, `TextField`, `Picker`) rather than custom hit-testing
+- Ensure **comfortable hit targets**; avoid tiny icons-only tap areas
+- Prefer **clear labels** over icon-only actions; use SF Symbols consistently with text where appropriate
+- Use appropriate keyboard/input behaviors (submit labels, autocorrection/capitalization) for the field's purpose
+- Avoid gesture-only interactions for primary actions; make actions discoverable
+
+### Examples
+
+```swift
+// ✅ Tappable control with label + icon; clear intent
+Button("Add item", systemImage: "plus") {
+    model.add()
+}
+.buttonStyle(.borderedProminent)
+
+// ✅ TextField with appropriate keyboard
+TextField("Email", text: $email)
+    .keyboardType(.emailAddress)
+    .textInputAutocapitalization(.never)
+    .autocorrectionDisabled()
+
+// ❌ Tiny icon-only tap target; poor discoverability
+Image(systemName: "plus")
+    .onTapGesture {
+        model.add()
+    }
+```
+
+## Navigation and Flows
+
+### Critical Rules
+
+- Prefer **NavigationStack + navigationDestination** for drill-in flows; keep navigation shallow where possible
+- Use **modals** for short, self-contained tasks (create, edit, pick); always provide a clear way to dismiss
+- Keep **back behavior predictable**: don't override system expectations; preserve navigation state when reasonable
+- Avoid "choice paralysis": limit top-level destinations; group related settings and utilities
+- Prefer system placements: `.confirmationAction` for Save/Done, `.cancellationAction` for Cancel
+
+### Examples
+
+```swift
+// ✅ Predictable drill-in navigation; modal only for creation
+NavigationStack {
+    List(items) { item in
+        NavigationLink(item.title, value: item.id)
+    }
+    .navigationDestination(for: Item.ID.self) { id in
+        ItemDetailView(id: id)
+    }
+    .toolbar {
+        ToolbarItem(placement: .primaryAction) {
+            Button("Add", systemImage: "plus") { model.isPresentingCreate = true }
+        }
+    }
+    .sheet(isPresented: $model.isPresentingCreate) {
+        NavigationStack { CreateItemView() }
+    }
+}
+
+// ✅ Modal with clear dismiss path
+NavigationStack {
+    CreateItemView()
+        .navigationTitle("New Item")
+        .toolbar {
+            ToolbarItem(placement: .cancellationAction) {
+                Button("Cancel", action: dismiss)
+            }
+            ToolbarItem(placement: .confirmationAction) {
+                Button("Save", action: model.save)
+            }
+        }
+}
+
+// ❌ Everything is a modal; unclear back/exit paths
+VStack {
+    Button("Open item") { model.showItem.toggle() }
+}
+.sheet(isPresented: $model.showItem) {
+    ItemDetailView(id: model.selectedID)
+        .toolbar { Button("Save") {} } // no Cancel, no navigation context
+}
+```
+
+### Navigation Guidelines
+
+**Use NavigationStack for**:
+- Browsing hierarchical content
+- Drill-down patterns
+- Main app navigation
+
+**Use Modals (.sheet, .fullScreenCover) for**:
+- Creating new content
+- Editing existing content
+- Short, self-contained tasks
+- Pickers and selections
+
+**Always provide**:
+- Clear dismiss buttons for modals
+- Consistent back button behavior
+- Confirmation for destructive actions
+
+## Layout, Hierarchy, and Grouping
+
+### Critical Rules
+
+- Design around **content first**: prioritize the primary task and content; remove decorative UI that doesn't help comprehension
+- Create **clear hierarchy**: one primary action per screen; secondary actions are visually subordinate
+- Use **consistent spacing and alignment** to communicate grouping; avoid "random" padding values across the app
+- Prefer system containers (`List`, `Form`, `Section`, `Toolbar`, `NavigationStack`) that encode platform layout conventions
+- Avoid dense UI: keep line lengths readable and allow whitespace for scanning
+
+### Examples
+
+```swift
+// ✅ Hierarchy + grouping via Sections; one primary action in toolbar
+NavigationStack {
+    List {
+        Section("Details") {
+            TextField("Title", text: $model.title)
+            TextField("Notes", text: $model.notes, axis: .vertical)
+        }
+
+        Section("Metadata") {
+            Toggle("Pinned", isOn: $model.isPinned)
+        }
+    }
+    .navigationTitle("New item")
+    .toolbar {
+        ToolbarItem(placement: .confirmationAction) {
+            Button("Save", action: model.save)
+        }
+    }
+}
+
+// ✅ Clear visual hierarchy with system components
+VStack(spacing: 16) {
+    // Primary action
+    Button("Continue", action: model.continue)
+        .buttonStyle(.borderedProminent)
+        .controlSize(.large)
+
+    // Secondary action
+    Button("Skip for now", action: model.skip)
+        .buttonStyle(.borderless)
+        .foregroundStyle(.secondary)
+}
+
+// ❌ Flat wall-of-controls with unclear priority
+VStack(spacing: 3) {
+    Text("New item").font(.title2)
+    TextField("Title", text: $model.title).padding(1)
+    TextField("Notes", text: $model.notes).padding(23)
+    Toggle("Pinned", isOn: $model.isPinned)
+    Button("Save", action: model.save)
+    Button("Delete", action: model.delete)
+}
+```
+
+### Layout Guidelines
+
+**Visual Hierarchy**:
+- One primary action per screen (prominent button style)
+- Secondary actions are visually subordinate (borderless, smaller)
+- Destructive actions are clearly marked (`.destructive` role)
+
+**Spacing and Grouping**:
+- Use `Section` in `List` or `Form` to group related controls
+- Consistent spacing values (8, 12, 16, 20, 24)
+- Whitespace communicates relationships
+
+**System Containers**:
+- `List` for browsable content
+- `Form` for data entry
+- `Section` for grouping
+- `Toolbar` for actions
+- `NavigationStack` for hierarchies
+
+## Summary
+
+**Key Principles**:
+1. Use system controls with comfortable hit targets
+2. NavigationStack for drill-down, modals for tasks
+3. Always provide clear dismiss paths
+4. One primary action per screen
+5. Use sections and spacing for grouping
+6. Prefer system containers over custom layouts

package/skills/ios/ios-hig/references/performance-platform.md

@@ -0,0 +1,129 @@
+# Performance and Platform Conventions
+
+Apple Human Interface Guidelines for performance, responsiveness, and platform-native patterns.
+
+## Table of Contents
+1. [Performance and Responsiveness](#performance-and-responsiveness)
+2. [Platform Conventions](#platform-conventions)
+
+## Performance and Responsiveness
+
+### Critical Rules
+
+- Optimize for **perceived performance**: show progress quickly, keep interactions responsive, and avoid blocking the main actor
+- Use incremental loading patterns where appropriate; avoid doing heavy work during view rendering
+- Prefer clear placeholder/progress UI over a frozen screen
+- Avoid unnecessary animations, shadows, and effects that degrade scrolling performance
+
+### Examples
+
+```swift
+// ✅ Immediate feedback and non-blocking load
+VStack {
+    if model.isLoading {
+        ProgressView("Loading…")
+    } else {
+        List(model.items) { item in Text(item.title) }
+    }
+}
+.task { await model.loadIfNeeded() }
+
+// ❌ Heavy synchronous work during view body; causes jank
+var body: some View {
+    let items = model.computeExpensiveListSynchronously()
+    return List(items) { item in Text(item.title) }
+}
+```
+
+### Performance Guidelines
+
+**Perceived Performance**:
+- Show UI immediately, even if data isn't ready
+- Use `ProgressView` or skeleton states while loading
+- Keep interactions responsive (<100ms feedback)
+- Avoid blocking the main thread
+
+**Async Work**:
+- Use `.task { }` for async loading in views
+- Move heavy computation to background tasks
+- Never do expensive work in `body` or computed properties
+
+**Rendering Performance**:
+- Avoid heavy shadows, blurs, or complex gradients in scrolling views
+- Use `LazyVStack`/`LazyHStack` for large lists
+- Profile with Instruments if scrolling feels janky
+
+**Loading Patterns**:
+- Show skeleton/placeholder UI immediately
+- Load data incrementally when appropriate
+- Provide progress indication for operations >1 second
+
+## Platform Conventions
+
+### Critical Rules
+
+- Prefer system components before custom UI (Lists, Forms, toolbars, menus, context menus)
+- Use SF Symbols consistently and pair icons with text for clarity when appropriate
+- Keep controls and terminology consistent with iOS conventions (Done/Cancel, Back, Edit)
+- Avoid recreating iOS UI patterns with bespoke visuals unless you have a strong UX reason
+
+### Examples
+
+```swift
+// ✅ System toolbar placements and familiar labels
+.toolbar {
+    ToolbarItem(placement: .cancellationAction) {
+        Button("Cancel", role: .cancel) { model.cancel() }
+    }
+    ToolbarItem(placement: .confirmationAction) {
+        Button("Done", action: model.done)
+    }
+}
+
+// ❌ Custom "Close" / "Okay" in random placements; inconsistent with platform
+.toolbar {
+    ToolbarItem(placement: .automatic) { Button("Okay") {} }
+    ToolbarItem(placement: .automatic) { Button("Close") {} }
+}
+```
+
+### Platform Guidelines
+
+**System Components**:
+- `List` for browsable content
+- `Form` for settings and data entry
+- `Toolbar` for actions
+- `NavigationStack` for hierarchical navigation
+- `Menu` and context menus for secondary actions
+
+**SF Symbols**:
+- Use SF Symbols for icons (system-provided, adapts to Dynamic Type)
+- Pair icons with text labels for clarity
+- Use consistent symbols throughout the app
+- Prefer standard symbols over custom icons
+
+**Platform Terminology**:
+- ✅ "Done", "Cancel", "Save", "Delete", "Edit"
+- ❌ "Okay", "Close", "Submit", "Remove", "Modify"
+
+**Standard Placements**:
+- `.cancellationAction` - Cancel/Back (leading on modals)
+- `.confirmationAction` - Done/Save (trailing on modals)
+- `.destructive` role for Delete actions
+- `.primaryAction` for main toolbar actions
+
+**Consistency**:
+- Follow iOS patterns for common flows (creation, editing, deletion)
+- Use standard gestures (swipe to delete, pull to refresh)
+- Respect system settings (Dynamic Type, Reduce Motion, Reduce Transparency)
+
+## Summary
+
+**Key Principles**:
+1. Show UI immediately; load data asynchronously
+2. Use `ProgressView` and skeleton states while loading
+3. Avoid heavy work during view rendering
+4. Prefer system components over custom UI
+5. Use SF Symbols and standard terminology
+6. Follow platform conventions for toolbar placements and actions
+7. Keep controls and terminology consistent with iOS

package/skills/ios/ios-hig/references/privacy-permissions.md

@@ -0,0 +1,181 @@
+# Privacy and Permissions
+
+Apple Human Interface Guidelines for requesting permissions and handling sensitive data.
+
+## Critical Rules
+
+- Request permissions **in context**, right before the feature needs it—never at app launch without cause
+- Explain **why** in user language and connect it to a clear benefit
+- If denied, provide a functional fallback and a clear path to Settings when appropriate
+- Minimize data collection; don't surface sensitive data in logs or UI where not needed
+
+## Examples
+
+### Permission Request Pattern
+
+```swift
+// ✅ Ask in context and handle denial gracefully
+Button("Enable notifications") {
+    model.requestNotifications()
+}
+// On denial: show a non-blocking explanation + "Open Settings" action
+
+// ❌ Permission request on launch with no context
+struct AppStart {
+    func start() {
+        model.requestNotifications()
+        model.requestLocation()
+    }
+}
+```
+
+### Complete Permission Flow
+
+```swift
+// ✅ Full permission flow with context and fallback
+struct NotificationSettingsView: View {
+    @State private var showingDeniedAlert = false
+
+    var body: some View {
+        VStack(spacing: 16) {
+            Text("Get notified when items are shared with you")
+                .font(.headline)
+
+            Text("Turn on notifications to stay updated when friends share links and notes.")
+                .font(.body)
+                .foregroundStyle(.secondary)
+
+            Button("Enable Notifications") {
+                Task {
+                    let granted = await requestNotificationPermission()
+                    if !granted {
+                        showingDeniedAlert = true
+                    }
+                }
+            }
+            .buttonStyle(.borderedProminent)
+        }
+        .alert("Notifications Disabled", isPresented: $showingDeniedAlert) {
+            Button("Open Settings") {
+                if let url = URL(string: UIApplication.openSettingsURLString) {
+                    UIApplication.shared.open(url)
+                }
+            }
+            Button("Not Now", role: .cancel) {}
+        } message: {
+            Text("To receive notifications, enable them in Settings.")
+        }
+    }
+
+    func requestNotificationPermission() async -> Bool {
+        let center = UNUserNotificationCenter.current()
+        do {
+            return try await center.requestAuthorization(options: [.alert, .sound, .badge])
+        } catch {
+            return false
+        }
+    }
+}
+```
+
+## Guidelines
+
+### When to Request Permissions
+
+**Good timing**:
+- Right before using the feature (user taps "Add location")
+- During feature onboarding (user enters location-based feature)
+- When user explicitly opts in (settings toggle)
+
+**Bad timing**:
+- App launch before any context
+- Background without user interaction
+- Bundled with other unrelated requests
+
+### How to Request Permissions
+
+**Clear value proposition**:
+- Explain the benefit in user terms
+- Show what they'll gain, not what you need
+- Use the feature's context to explain why
+
+**Examples**:
+- ✅ "Get notified when items are shared with you"
+- ❌ "This app would like to send you notifications"
+- ✅ "Save your location to remember where you found this"
+- ❌ "Allow location access"
+
+### Handling Denial
+
+**Graceful fallback**:
+- Don't block the entire feature if possible
+- Provide alternative workflows
+- Only show Settings path if user might want to change their mind
+
+**Examples**:
+- Location denied → Manual address entry
+- Notifications denied → In-app badge/indicator
+- Camera denied → Photo library picker
+
+### Privacy Best Practices
+
+**Data minimization**:
+- Only request what you actually need
+- Don't log sensitive data (passwords, tokens, personal info)
+- Don't display sensitive data in UI unless necessary
+- Clear sensitive data when no longer needed
+
+**User control**:
+- Provide clear settings to manage data
+- Allow users to delete their data
+- Respect system privacy settings
+
+## Common Permissions
+
+### Notifications
+
+```swift
+// Request with UNUserNotificationCenter
+let granted = try await UNUserNotificationCenter.current()
+    .requestAuthorization(options: [.alert, .sound, .badge])
+```
+
+**When to ask**: Before subscribing to notification topics or when user enables a notification-dependent feature
+
+### Location
+
+```swift
+// Request with CLLocationManager
+locationManager.requestWhenInUseAuthorization()
+```
+
+**When to ask**: Right before adding a location-based item or enabling location features
+
+### Photos
+
+```swift
+// Request with PHPhotoLibrary
+let status = await PHPhotoLibrary.requestAuthorization(for: .readWrite)
+```
+
+**When to ask**: When user taps "Add photo" or similar action
+
+### Camera
+
+```swift
+// Request with AVCaptureDevice
+let granted = await AVCaptureDevice.requestAccess(for: .video)
+```
+
+**When to ask**: Right before showing camera interface
+
+## Summary
+
+**Key Principles**:
+1. Request permissions in context, never at app launch
+2. Explain the benefit in user terms
+3. Handle denial gracefully with fallbacks
+4. Provide path to Settings when appropriate
+5. Minimize data collection and logging
+6. Respect system privacy settings
+7. Give users control over their data

package/skills/ios/ios-hig/references/visual-design.md

@@ -0,0 +1,84 @@
+# Visual Design
+
+Apple Human Interface Guidelines for color, materials, and contrast.
+
+## Critical Rules
+
+- Prefer **semantic system styles** (`.tint`, `.secondary`, `.tertiary`, `Material`) over custom colors
+- Support **light and dark mode**; don't rely on "always light" colors
+- Maintain **sufficient contrast** for text and controls, including in accessibility settings
+- Use color to **reinforce meaning**, not as the only indicator (pair with text/icons)
+- Avoid decorative gradients/materials that reduce readability or increase visual noise
+
+## Examples
+
+### Semantic System Styles
+
+```swift
+// ✅ Semantic styles that adapt automatically
+HStack {
+    Image(systemName: "link")
+        .foregroundStyle(.tint)
+    Text("Open link")
+        .foregroundStyle(.primary)
+    Spacer()
+    Text("Optional")
+        .foregroundStyle(.secondary)
+}
+.padding()
+.background(.thinMaterial)
+.clipShape(.rect(cornerRadius: 12))
+
+// ❌ Hard-coded colors that can break contrast in dark mode
+HStack {
+    Text("Open link")
+        .foregroundStyle(Color.white)
+}
+.padding()
+.background(Color.yellow)
+.clipShape(.rect(cornerRadius: 12))
+```
+
+### Light and Dark Mode Support
+
+```swift
+// ✅ Adapts to light/dark mode automatically
+VStack {
+    Text("Title")
+        .foregroundStyle(.primary)
+    Text("Subtitle")
+        .foregroundStyle(.secondary)
+}
+.background(.background)
+
+// ❌ Hard-coded colors don't adapt
+VStack {
+    Text("Title")
+        .foregroundStyle(Color.black)
+    Text("Subtitle")
+        .foregroundStyle(Color.gray)
+}
+.background(Color.white)
+```
+
+### Color + Meaning
+
+```swift
+// ✅ Color reinforces meaning with text/icon
+Label("Error occurred", systemImage: "exclamationmark.triangle")
+    .foregroundStyle(.red)
+
+// ❌ Color alone conveys meaning
+Circle()
+    .fill(Color.red)
+    .frame(width: 8, height: 8)
+```
+
+## Summary
+
+**Key Principles**:
+1. Use semantic color styles (`.primary`, `.secondary`, `.tint`)
+2. Support both light and dark appearance modes
+3. Ensure sufficient contrast for readability
+4. Pair color with text or icons for meaning
+5. Use materials (`.thinMaterial`, `.regularMaterial`) for depth