screenshot-automation

What this skill does

# Screenshot Automation Generator

Generate an automated App Store screenshot pipeline that captures screenshots via UI tests, adds localized marketing captions, applies device frames, and exports all required sizes for App Store Connect. Saves hours of manual screenshot creation every release.

## When This Skill Activates

Use this skill when the user:
- Asks about "screenshot automation" or "automate screenshots"
- Wants to generate "App Store screenshots" or "store screenshots"
- Mentions "automated screenshots" or "screenshot pipeline"
- Asks to "generate screenshots" or "batch screenshots"
- Wants "screenshot testing" or "UI test screenshots"
- Mentions "fastlane snapshot" or wants a replacement for it

## Pre-Generation Checks

### 1. Project Context Detection
- [ ] Check Swift version (requires Swift 5.9+)
- [ ] Check deployment target (iOS 16+ / macOS 13+)
- [ ] Identify existing UI test target (look for `*UITests` target)
- [ ] Check for existing UI test files
- [ ] Check for fastlane presence (`Fastfile`, `Snapfile`)

### 2. Conflict Detection
Search for existing screenshot infrastructure:
```
Glob: **/*Screenshot*.swift, **/*Snapshot*.swift, **/Snapfile, **/Fastfile
Grep: "XCTAttachment" or "screenshot" or "snapshot" in UI test files
```

If fastlane snapshot already configured:
- Ask if user wants to replace or augment it
- If keeping fastlane, generate only the post-processing pipeline

### 3. Localization Detection
Check for existing localization setup:
```
Glob: **/*.lproj/*.strings, **/*Localizable*, **/*.xcstrings
```
Determine which locales are already configured in the project.

## Configuration Questions

Ask user via AskUserQuestion:

1. **Screenshot capture method?**
   - XCUITest only (pure Apple, no dependencies)
   - fastlane snapshot (uses fastlane tooling)
   - Both (XCUITest capture + fastlane orchestration)

2. **Target devices?** (multi-select)
   - iPhone 6.7" (iPhone 15 Pro Max / 16 Pro Max) -- required for App Store
   - iPhone 6.5" (iPhone 11 Pro Max / XS Max) -- required for older slot
   - iPhone 5.5" (iPhone 8 Plus) -- optional legacy
   - iPad 12.9" (iPad Pro 6th gen) -- required if universal app
   - iPad 11" (iPad Air) -- optional

3. **Locales?**
   - en-US only
   - en-US + (list additional locales, e.g., de-DE, ja-JP, fr-FR, es-ES, zh-Hans)
   - Match existing project localizations

4. **Include device frames?**
   - Yes (wrap screenshots in device bezels for marketing)
   - No (raw screenshots only)

5. **Caption overlay style?**
   - Top (marketing text above the screenshot)
   - Bottom (marketing text below the screenshot)
   - None (no text overlay, raw screenshot or framed only)

## Generation Process

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

### Step 2: Create App-Side Screenshot Mode
Generate:
1. `ScreenshotModeController.swift` -- **Add to the app target (not tests)**. Detects `--screenshot-mode` launch argument and configures the app: suppresses onboarding, disables analytics/IAP, loads sample data, sizes windows (macOS). Also provides `@Environment(\.isScreenshotMode)` for views to hide promotional UI during capture.

Tell the user to:
- Call `ScreenshotModeController.shared.configureIfNeeded()` in their App's `init()`
- Call `ScreenshotModeController.shared.configureWindow()` in their root view's `onAppear`
- Override `loadSampleData()` to populate their data store with attractive content

### Step 3: Create Configuration
Generate:
2. `ScreenshotPlan.swift` -- Defines screens to capture, devices, locales, and output paths

### Step 4: Create UI Test Files
Generate:
3. `ScreenshotUITests.swift` -- XCUITest class that navigates and captures each screen
4. `ScreenshotTestHelper.swift` -- Helper utilities for locale setup, data seeding, alert dismissal, plus `tapUnhittable()` extension for custom controls

### Step 5: Create Post-Processing Files
Generate:
5. `ScreenshotProcessor.swift` -- Loads captured images, routes through framing and captioning
6. `CaptionOverlay.swift` -- Renders localized marketing text onto screenshot images

For macOS-only or lightweight needs, offer `sips-screenshot-process.sh` as an alternative to the Swift processor. Uses macOS's built-in `sips` command — zero dependencies.

### Step 6: Create Export Script
Generate:
7. `ScreenshotExportScript.swift` -- End-to-end pipeline script: build, test, process, organize

For macOS apps, also generate:
8. `macos-screenshot-env.sh` -- Desktop preparation script (hides dock, desktop icons, simplifies clock) with `trap`-based cleanup

### Step 7: Create Sample Content Generator
If the user needs realistic sample data for screenshots:
9. `SampleContentGenerator.swift` -- Provides text content, chart data, placeholder images, and PDF generation (macOS). Category-specific sample titles for productivity, fitness, finance, and notes apps.

### Step 8: Create Xcode Test Plan
Generate:
10. `ScreenshotTests.xctestplan` -- Dedicated test plan that isolates screenshot tests from development tests. Prevents screenshot tests from running during `Cmd+U`.

Tell the user to:
- Save to project root
- Add to their scheme via Product → Scheme → Edit Scheme → Test → add plan
- Run with: `xcodebuild test -testPlan "ScreenshotTests" ...`

### Step 9: Determine File Locations
Check project structure:
- `ScreenshotModeController.swift` goes into the **app target** source directory
- `SampleContentGenerator.swift` goes into the **app target** source directory
- UI test files go into the existing `*UITests/` target directory
- Processing files go into a `ScreenshotAutomation/` group or `Scripts/` directory
- Shell scripts go into `Scripts/` directory
- Test plan goes into the project root
- If `Sources/` exists -> `Sources/ScreenshotAutomation/`
- Otherwise -> `ScreenshotAutomation/`

## Output Format

After generation, provide:

### Files Created
```
App Target (source directory):
├── ScreenshotModeController.swift  # App-side screenshot mode detection & config
└── SampleContentGenerator.swift    # Realistic sample data for screenshots

UITests Target:
├── ScreenshotUITests.swift         # XCUITest capture class
└── ScreenshotTestHelper.swift      # Helper: locale, seeding, alerts, tapUnhittable()

ScreenshotAutomation/:
├── ScreenshotPlan.swift            # Configuration: screens, devices, locales
├── ScreenshotProcessor.swift       # Post-processing orchestrator
├── CaptionOverlay.swift            # Localized text overlay renderer
└── ScreenshotExportScript.swift    # Full pipeline script

Scripts/ (shell scripts):
├── sips-screenshot-process.sh      # Lightweight sips-based image processing
└── macos-screenshot-env.sh         # macOS desktop prep with trap cleanup

Project Root:
└── ScreenshotTests.xctestplan      # Dedicated test plan for screenshots
```

### Integration with CI

**Xcode Cloud:**
```yaml
# ci_scripts/ci_post_xcodebuild.sh
if [ "$CI_WORKFLOW" = "Screenshots" ]; then
    swift ScreenshotAutomation/ScreenshotExportScript.swift
fi
```

**GitHub Actions:**
```yaml
- name: Generate Screenshots
  run: |
    xcodebuild test \
      -scheme "YourAppUITests" \
      -destination "platform=iOS Simulator,name=iPhone 16 Pro Max" \
      -testPlan ScreenshotPlan \
      -resultBundlePath screenshots.xcresult
    swift ScreenshotAutomation/ScreenshotExportScript.swift
```

**fastlane (if selected):**
```ruby
lane :screenshots do
  capture_screenshots(scheme: "YourAppUITests")
  # Post-processing handled by ScreenshotProcessor
end
```

### Testing and Running

**Run screenshot tests from Xcode:**
```bash
xcodebuild test \
  -project YourApp.xcodeproj \
  -scheme "YourAppUITests" \
  -destination "platform=iOS Simulator,name=iPhone 16 Pro Max" \
  -only-testing "YourAppUITests/ScreenshotUITests"
```

**Run the full pipeline:**
```bash
swift ScreenshotAutomation/ScreenshotExportScript.swift
```

**Verify output directory:**
```
screenshots/
├── en-US/
│   ├── iPhone_6.7/
│   │   ├── 01_HomeScreen.png
│   │