permission-priming

# Permission Priming Generator

Generate pre-permission priming screens — shown before iOS system permission dialogs to explain WHY the app needs access. Dramatically increases permission grant rates vs. cold-prompting users with the system alert.

## When This Skill Activates

Use this skill when the user:
- Asks to "add permission priming" or "pre-permission screen"
- Mentions "explain permissions" or "permission request screen"
- Wants to "ask for camera permission" or "notification permission"
- Asks about "location permission explanation" or "permission grant rate"
- Wants to "prime before requesting access" or "improve opt-in rates"
- Mentions "permission dialog" or "permission flow"

## Pre-Generation Checks

### 1. Project Context Detection
- [ ] Check deployment target (iOS 16+ / macOS 13+)
- [ ] Check for @Observable support (iOS 17+ / macOS 14+)
- [ ] Identify source file locations

### 2. Existing Permission Code
Search for existing permission handling:
```
Glob: **/*Permission*.swift, **/*Authorization*.swift
Grep: "requestAuthorization" or "AVCaptureDevice" or "UNUserNotificationCenter" or "CLLocationManager" or "PHPhotoLibrary"
```

If existing permission code found:
- Ask if user wants to wrap existing calls with priming screens or replace entirely
- If wrapping, integrate priming views upstream of existing request calls

### 3. Info.plist Usage Description Strings
Search for required usage description keys:
```
Grep: "NSCameraUsageDescription" or "NSMicrophoneUsageDescription" or "NSLocationWhenInUseUsageDescription" or "NSPhotoLibraryUsageDescription" or "NSContactsUsageDescription" or "NSHealthShareUsageDescription"
```

If missing keys found for requested permissions:
- Warn user that the app will crash without the corresponding Info.plist entry
- Provide the required key and a suggested description string

## Configuration Questions

Ask user via AskUserQuestion:

1. **Which permissions to prime?** (multi-select)
   - Push Notifications
   - Camera
   - Photo Library
   - Location (When In Use)
   - Location (Always)
   - Microphone
   - Contacts
   - Health (HealthKit)
   - App Tracking Transparency (ATT)

2. **Priming style?**
   - Full-screen (dedicated view with illustration, title, benefits, CTA) — recommended
   - Alert-style (compact alert-like overlay before system prompt)
   - Inline (embedded card within existing content)

3. **Include "Not Now" option?**
   - Yes (recommended — reduces user frustration, can re-prompt later)
   - No (only "Enable" button — more aggressive)

4. **Show benefits illustration?**
   - SF Symbol (simple, matches system style)
   - Custom illustration area (placeholder for designer asset)
   - None (text only)

## Generation Process

### Step 1: Read Templates
Read `templates.md` for production Swift code.

### Step 2: Create Core Files
Generate these files:
1. `PermissionType.swift` — Enum of all permission types with metadata
2. `PermissionStatus.swift` — Unified status enum wrapping platform-specific statuses
3. `PermissionManager.swift` — @Observable class that checks, requests, and opens Settings

### Step 3: Create UI Files
4. `PermissionPrimingView.swift` — Pre-permission screen with benefits and CTA
5. `PermissionStatusTracker.swift` — Monitors status changes from Settings

### Step 4: Create Modifier Files
6. `PermissionGatedModifier.swift` — ViewModifier that gates content behind permission check

### Step 5: Determine File Location
Check project structure:
- If `Sources/` exists -> `Sources/Permissions/`
- If `App/` exists -> `App/Permissions/`
- Otherwise -> `Permissions/`

## Output Format

After generation, provide:

### Files Created
```
Permissions/
├── PermissionType.swift            # Permission enum with metadata
├── PermissionStatus.swift          # Unified status wrapper
├── PermissionManager.swift         # Check, request, open Settings
├── PermissionPrimingView.swift     # Pre-permission priming screen
├── PermissionStatusTracker.swift   # Monitor status changes
└── PermissionGatedModifier.swift   # Gate content behind permission
```

### Integration Steps

**Basic priming before system prompt:**
```swift
// Show priming screen, then request system permission on tap
PermissionPrimingView(permissionType: .notifications) {
    // User granted — proceed with feature
    startSendingNotifications()
} onDenied: {
    // User denied or tapped "Not Now"
    showLaterPrompt()
}
```

**Gate a feature behind permission:**
```swift
// Camera feature gated behind permission
CameraView()
    .permissionGated(.camera) {
        // Priming screen shown automatically if not yet authorized
    }
```

**In onboarding flow:**
```swift
struct OnboardingPermissionsView: View {
    @State private var permissionManager = PermissionManager()

    var body: some View {
        VStack(spacing: 32) {
            PermissionPrimingView(permissionType: .notifications) {
                // Move to next permission
            } onDenied: {
                // Skip, ask later
            }
        }
    }
}
```

**Check status and re-prompt after denial:**
```swift
struct SettingsView: View {
    @State private var permissionManager = PermissionManager()

    var body: some View {
        Section("Permissions") {
            ForEach(PermissionType.allCases, id: \.self) { type in
                PermissionRow(
                    type: type,
                    status: permissionManager.status(for: type),
                    onRequest: { permissionManager.openSettings() }
                )
            }
        }
    }
}
```

### Testing

```swift
@Test
func primingViewShowsBeforeSystemPrompt() async throws {
    let manager = PermissionManager()
    let status = await manager.status(for: .notifications)
    #expect(status == .notDetermined)
    // Priming view should appear before system dialog
}

@Test
func deniedPermissionDirectsToSettings() async throws {
    let manager = PermissionManager()
    // After denial, tapping "Enable" should open Settings
    let settingsURL = manager.settingsURL
    #expect(settingsURL != nil)
}

@Test
func permissionGatedModifierShowsPrimingWhenNotAuthorized() async throws {
    // ViewModifier should show priming screen when permission is .notDetermined
    // and show content when .authorized
}
```

## Common Patterns

### Prime Before First Use
Show priming screen at the natural moment the user first needs the feature, not during onboarding:
```swift
// User taps "Take Photo" -> show camera priming -> then system prompt
Button("Take Photo") {
    showCameraPriming = true
}
.sheet(isPresented: $showCameraPriming) {
    PermissionPrimingView(permissionType: .camera,
                          onGranted: { openCamera() },
                          onDenied: { showCameraPriming = false })
}
```

### Contextual Priming
Explain the benefit in context of what the user is trying to do:
```swift
PermissionPrimingView(
    permissionType: .location(.whenInUse),
    customTitle: "Find Nearby Restaurants",
    customDescription: "We use your location to show restaurants within walking distance."
) { ... }
```

### Re-Request After Denial
After denial, the system prompt cannot be shown again. Direct to Settings:
```swift
if permissionManager.status(for: .camera) == .denied {
    // Show explanation + "Open Settings" button
    PermissionDeniedView(permissionType: .camera) {
        permissionManager.openSettings()
    }
}
```

## Gotchas

- **Cannot re-show system prompt after denial.** Once the user denies a permission, iOS will never show the system dialog again. You must direct the user to Settings > Privacy to re-enable. Always handle the `.denied` state gracefully.
- **App Tracking Transparency (ATT) has special requirements.** ATT must be requested before tracking begins. The priming screen must NOT use misleading language. Apple reviews ATT implementations closely — avoid incentivizing users to allow tracking.
- **Health permissions have unique two-column UI.** HealthKit authorization uses its own system sheet with read/write toggles per data type. You cannot customize it. Your priming screen should explain which health data you need and why before presenting the HealthKit sheet.
- **Location "Always" requires progressive authorization.** You must first request `.whenInUse`, then separately request `.always`. iOS shows a follow-up prompt only after the user has used the app with When In Use access. Do not request Always upfront.
- **Provisional notifications (iOS 12+) bypass the prompt entirely.** With `.provisional`, notifications are delivered silently to Notification Center without asking. Consider whether quiet delivery is acceptable before building a priming screen.
- **Info.plist keys are mandatory.** If you call a permission API without the corresponding `NS*UsageDescription` key in Info.plist, the app will crash immediately. Always verify these keys exist.

## References

- **templates.md** — All production Swift templates for permission priming
- Related: `generators/push-notifications` — Push notification setup and handling
- Related: `generators/consent-flow` — GDPR/privacy consent flows