buildanything 1.8.0 → 2.1.1

package/skills/ios/_VENDORED.md

@@ -9,6 +9,7 @@ _Wholesale copies from `research/swift-skills/` per `research/swift-skills/_docs
 | swift-security-expert | ivan-magda/swift-security-skill | MIT | Ivan Magda | 2026-04-04 |
 | swiftdata-pro | twostraws/SwiftData-Agent-Skill | MIT | Paul Hudson | 2026-04-04 |
 | swift-testing-expert | AvdLee/Swift-Testing-Agent-Skill | MIT | Antoine van der Lee | 2026-04-04 |
+| swift-testing | bocato/swift-testing-agent-skill | MIT | bocato | 2026-04-18 |
 | swift-accessibility | PasqualeVittoriosi/swift-accessibility-skill | MIT | Pasquale Vittoriosi | 2026-04-04 |
 | swiftui-ui-patterns | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
 | swiftui-view-refactor | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
@@ -58,3 +59,4 @@ Authored in-house for the buildanything plugin. Not vendored from upstream.
 | ios-entitlements-generator | expanding | Derive `.entitlements` file from required iOS capabilities (Keychain, Push, HealthKit, etc.) | stub | 2026-04-04 |
 | ios-info-plist-hardening | expanding | Populate Info.plist usage-description strings, ATS settings, privacy manifest alignment | stub | 2026-04-04 |
 | ios-maestro-flow-author | expanding | Author Maestro `.yaml` E2E flows for critical user journeys | stub | 2026-04-04 |
+| writing-for-interfaces | ready | Microcopy + tone review for iOS interface text | stub | 2026-04-18 |

package/skills/ios/app-store-connect-metadata/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: asc-metadata-sync
+description: Sync and validate App Store metadata and localizations with asc, including legacy metadata format migration. Use when updating metadata or translations.
+---
+
+# asc metadata sync
+
+Use this skill to keep local metadata in sync with App Store Connect.
+
+## Two Types of Localizations
+
+### 1. Version Localizations (per-release)
+Fields: `description`, `keywords`, `whatsNew`, `supportUrl`, `marketingUrl`, `promotionalText`
+
+```bash
+# List version localizations
+asc localizations list --version "VERSION_ID"
+
+# Download
+asc localizations download --version "VERSION_ID" --path "./localizations"
+
+# Upload from .strings files
+asc localizations upload --version "VERSION_ID" --path "./localizations"
+```
+
+### 2. App Info Localizations (app-level)
+Fields: `name`, `subtitle`, `privacyPolicyUrl`, `privacyChoicesUrl`, `privacyPolicyText`
+
+```bash
+# First, find the app info ID
+asc apps info list --app "APP_ID"
+
+# List app info localizations
+asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID"
+
+# Upload app info localizations
+asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
+```
+
+**Note:** If you get "multiple app infos found", you must specify `--app-info` with the correct ID.
+
+## Legacy Fastlane Metadata Workflow
+
+### Export current state
+```bash
+asc migrate export --app "APP_ID" --version-id "VERSION_ID" --output-dir "./fastlane"
+```
+
+### Validate local files
+```bash
+asc migrate validate --fastlane-dir "./fastlane"
+```
+This checks character limits and required fields.
+
+### Import updates
+```bash
+asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir "./fastlane" --dry-run
+asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir "./fastlane"
+```
+
+## Quick Field Updates
+
+### Version-specific fields
+```bash
+# What's New
+asc apps info edit --app "APP_ID" --locale "en-US" --whats-new "Bug fixes and improvements"
+
+# Description
+asc apps info edit --app "APP_ID" --locale "en-US" --description "Your app description here"
+
+# Keywords
+asc apps info edit --app "APP_ID" --locale "en-US" --keywords "keyword1,keyword2,keyword3"
+
+# Support URL
+asc apps info edit --app "APP_ID" --locale "en-US" --support-url "https://support.example.com"
+```
+
+### Version metadata
+```bash
+# Copyright
+asc versions update --version-id "VERSION_ID" --copyright "2026 Your Company"
+
+# Release type
+asc versions update --version-id "VERSION_ID" --release-type AFTER_APPROVAL
+```
+
+### TestFlight notes
+```bash
+asc build-localizations create --build "BUILD_ID" --locale "en-US" --whats-new "TestFlight notes here"
+```
+
+## .strings File Format
+
+For bulk updates, use .strings files:
+
+```
+// en-US.strings
+"description" = "Your app description";
+"keywords" = "keyword1,keyword2,keyword3";
+"whatsNew" = "What's new in this version";
+"supportUrl" = "https://support.example.com";
+```
+
+For app-info type:
+```
+// en-US.strings (app-info type)
+"privacyPolicyUrl" = "https://example.com/privacy";
+"name" = "Your App Name";
+"subtitle" = "Your subtitle";
+```
+
+## Multi-Language Workflow
+
+1. Export all localizations:
+```bash
+asc localizations download --version "VERSION_ID" --path "./localizations"
+```
+
+2. Translate the .strings files (or use translation service)
+
+3. Upload all at once:
+```bash
+asc localizations upload --version "VERSION_ID" --path "./localizations"
+```
+
+4. Verify:
+```bash
+asc localizations list --version "VERSION_ID" --output table
+```
+
+## Character Limits
+
+| Field | Limit |
+|-------|-------|
+| Name | 30 |
+| Subtitle | 30 |
+| Keywords | 100 (comma-separated) |
+| Description | 4000 |
+| What's New | 4000 |
+| Promotional Text | 170 |
+
+Use `asc metadata validate --dir "./metadata"` for canonical metadata trees.
+Use `asc migrate validate --fastlane-dir "./fastlane"` for legacy fastlane-format metadata.
+
+## Notes
+- Version localizations and app info localizations are different; use the right command and `--type` flag.
+- Use `asc localizations list` to confirm available locales and IDs.
+- Privacy Policy URL is in app info localizations, not version localizations.

package/skills/ios/asc-privacy-manifest/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: asc-privacy-manifest
+description: Generate and validate PrivacyInfo.xcprivacy files for iOS apps — required reason APIs, collected data types, tracking declarations, and SDK aggregation.
+license: MIT
+metadata:
+  author: oneshot
+  version: "1.0.0"
+---
+
+# iOS Privacy Manifest (PrivacyInfo.xcprivacy)
+
+Since iOS 17 / Xcode 15, every app and third-party SDK must ship a `PrivacyInfo.xcprivacy` file declaring what data it collects, which privacy-sensitive APIs it calls, and whether it tracks users. App Store Connect rejects submissions that omit required entries (ITMS-91053, ITMS-91055).
+
+## File structure
+
+`PrivacyInfo.xcprivacy` is a property list (XML plist) with four top-level keys:
+
+| Key | Type | Purpose |
+|-----|------|---------|
+| `NSPrivacyTracking` | Boolean | `true` if the app tracks users per ATT definition |
+| `NSPrivacyTrackingDomains` | Array of String | Domains contacted for tracking (only when tracking is true) |
+| `NSPrivacyCollectedDataTypes` | Array of Dict | Each data category collected, with purpose and linkage |
+| `NSPrivacyAccessedAPITypes` | Array of Dict | Each required-reason API category used, with reason codes |
+
+## 1. Required reason APIs (NSPrivacyAccessedAPITypes)
+
+Five API categories require declared reasons. Each entry is a dict with `NSPrivacyAccessedAPIType` (category string) and `NSPrivacyAccessedAPITypeReasons` (array of reason codes).
+
+### File timestamp APIs — `NSPrivacyAccessedAPICategoryFileTimestamp`
+
+Triggered by: `FileManager` attribute reads (`modificationDate`, `creationDate`), `stat()`, `fstat()`, `getattrlist()`, `NSFileModificationDate`, `NSURLContentModificationDateKey`, `NSURLCreationDateKey`.
+
+| Code | Meaning |
+|------|---------|
+| `DDA9.1` | Display file timestamps to the user on-device only (no off-device transmission) |
+| `C617.1` | Access file metadata inside app container, app group container, or CloudKit container |
+| `3B52.1` | Access metadata for files the user explicitly selected (document picker, drag-and-drop) |
+| `0A2A.1` | Third-party SDK wrapper — only when the host app invokes the wrapper API |
+
+### System boot time APIs — `NSPrivacyAccessedAPICategorySystemBootTime`
+
+Triggered by: `ProcessInfo.processInfo.systemUptime`, `mach_absolute_time()`, `clock_gettime(CLOCK_MONOTONIC)`.
+
+| Code | Meaning |
+|------|---------|
+| `35F9.1` | Measure elapsed time between events within the app |
+| `8FFB.1` | Calculate absolute timestamps for events (e.g. UIKit or AVFAudio timestamps) |
+| `3D61.1` | Include boot time in an optional, user-initiated bug report |
+
+### Disk space APIs — `NSPrivacyAccessedAPICategoryDiskSpace`
+
+Triggered by: `FileManager` `attributesOfFileSystem(forPath:)`, `volumeAvailableCapacityKey`, `volumeTotalCapacityKey`, `statfs()`, `statvfs()`.
+
+| Code | Meaning |
+|------|---------|
+| `85F4.1` | Display disk space information to the user on-device |
+| `E174.1` | Check available space before writing files or delete files on low disk |
+| `7D9E.1` | Include disk space in an optional, user-initiated bug report |
+| `B728.1` | Health research apps detecting low disk for data integrity |
+
+### Active keyboards APIs — `NSPrivacyAccessedAPICategoryActiveKeyboards`
+
+Triggered by: `UITextInputMode.activeInputModes`.
+
+| Code | Meaning |
+|------|---------|
+| `3EC4.1` | Custom keyboard app checking which keyboards are active |
+| `54BD.1` | Customize UI or input behavior based on active keyboards |
+
+### User defaults APIs — `NSPrivacyAccessedAPICategoryUserDefaults`
+
+Triggered by: `UserDefaults` standard or suite access. Almost every app hits this.
+
+| Code | Meaning |
+|------|---------|
+| `CA92.1` | Read/write data accessible only to the app itself |
+| `1C8F.1` | Read/write data shared via App Group (app + widgets/extensions) |
+| `C56D.1` | Third-party SDK wrapper providing access to user defaults |
+| `AC6B.1` | Read managed app configuration or write feedback for MDM |
+
+## 2. Collected data types (NSPrivacyCollectedDataTypes)
+
+Each dict in the array declares one data category with four keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `NSPrivacyCollectedDataType` | String | Identifier from Apple's predefined list |
+| `NSPrivacyCollectedDataTypeLinked` | Boolean | `true` if this data is linked to the user's identity |
+| `NSPrivacyCollectedDataTypeTracking` | Boolean | `true` if this data is used for tracking |
+| `NSPrivacyCollectedDataTypePurposes` | Array of String | Why this data is collected |
+
+### Common data type identifiers
+
+| Identifier | Category |
+|------------|----------|
+| `NSPrivacyCollectedDataTypeName` | Contact info — name |
+| `NSPrivacyCollectedDataTypeEmailAddress` | Contact info — email |
+| `NSPrivacyCollectedDataTypePhoneNumber` | Contact info — phone |
+| `NSPrivacyCollectedDataTypeUserID` | Identifiers — user ID |
+| `NSPrivacyCollectedDataTypeDeviceID` | Identifiers — device ID (IDFA, IDFV) |
+| `NSPrivacyCollectedDataTypePreciseLocation` | Location — precise |
+| `NSPrivacyCollectedDataTypeCoarseLocation` | Location — coarse |
+| `NSPrivacyCollectedDataTypeProductInteraction` | Usage data — product interaction |
+| `NSPrivacyCollectedDataTypeOtherUsageData` | Usage data — other |
+| `NSPrivacyCollectedDataTypeCrashData` | Diagnostics — crash data |
+| `NSPrivacyCollectedDataTypePerformanceData` | Diagnostics — performance |
+| `NSPrivacyCollectedDataTypeOtherDiagnosticData` | Diagnostics — other |
+| `NSPrivacyCollectedDataTypePaymentInfo` | Financial — payment info |
+| `NSPrivacyCollectedDataTypePhotosorVideos` | User content — photos/videos |
+| `NSPrivacyCollectedDataTypeContacts` | User content — contacts |
+| `NSPrivacyCollectedDataTypeHealth` | Health & fitness |
+| `NSPrivacyCollectedDataTypeFitness` | Health & fitness |
+| `NSPrivacyCollectedDataTypeOtherDataTypes` | Catch-all |
+
+### Purpose identifiers
+
+| Identifier | Meaning |
+|------------|---------|
+| `NSPrivacyCollectedDataTypePurposeAppFunctionality` | Core app features |
+| `NSPrivacyCollectedDataTypePurposeAnalytics` | Analytics |
+| `NSPrivacyCollectedDataTypePurposeProductPersonalization` | Personalization |
+| `NSPrivacyCollectedDataTypePurposeDeveloperAdvertising` | Developer's own ads/marketing |
+| `NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising` | Third-party ad networks |
+| `NSPrivacyCollectedDataTypePurposeOther` | Other purposes |
+
+## 3. Tracking and ATT (NSPrivacyTracking)
+
+Set `NSPrivacyTracking` to `true` only if the app links collected data with third-party data for advertising or ad measurement. This aligns with Apple's App Tracking Transparency (ATT) definition.
+
+When `NSPrivacyTracking` is `true`:
+- The app **must** call `ATTrackingManager.requestTrackingAuthorization()` before tracking.
+- `NSPrivacyTrackingDomains` must list every domain contacted for tracking purposes.
+- iOS blocks network requests to listed domains when the user denies tracking permission.
+- `Info.plist` must include `NSUserTrackingUsageDescription` with a user-facing explanation.
+
+When `NSPrivacyTracking` is `false`, leave `NSPrivacyTrackingDomains` as an empty array.
+
+## 4. Third-party SDK manifests and aggregation
+
+Each SDK must bundle its own `PrivacyInfo.xcprivacy` inside its framework or Swift package bundle. During archival, Xcode aggregates all manifests into a unified **Privacy Report** (accessible via Product > Generate Privacy Report in Xcode).
+
+Rules:
+- The app's manifest covers the app target only — not its dependencies.
+- Each framework/xcframework/Swift package provides its own manifest.
+- Xcode merges all manifests at archive time; duplicates are union-merged.
+- If an SDK lacks a manifest, App Store Connect flags the submission (ITMS-91061).
+- Update third-party SDKs regularly — most major SDKs (Alamofire, Firebase, Sentry, etc.) ship manifests since mid-2024.
+
+For Swift packages: place `PrivacyInfo.xcprivacy` in the package's resource bundle and declare it in `Package.swift` via `.process("PrivacyInfo.xcprivacy")` in the target's `resources` array.
+
+## 5. Xcode integration
+
+### Where to place the file
+- **App target**: project root, alongside `Info.plist`. Xcode copies it into the app bundle at build time.
+- **Framework target**: inside the framework's bundle resources.
+- **Swift Package**: in `Sources/<Target>/` and declared in `Package.swift` resources.
+
+### How to create it in Xcode
+1. File > New > File (or Cmd-N).
+2. Search for "App Privacy" and select the template.
+3. Choose the correct target in the file inspector.
+4. Xcode creates `PrivacyInfo.xcprivacy` with a visual editor for the four top-level keys.
+
+The file **must** be named exactly `PrivacyInfo.xcprivacy` — Apple's tooling scans for this specific filename.
+
+### Generate a privacy report
+1. Archive the app (Product > Archive).
+2. Right-click the archive in the Organizer > Generate Privacy Report.
+3. Review the aggregated report for missing entries before submission.
+
+## 6. Common App Store rejection reasons
+
+| Error code | Cause | Fix |
+|------------|-------|-----|
+| ITMS-91053 | App uses a required-reason API without declaring it in the manifest | Add the missing `NSPrivacyAccessedAPIType` entry with valid reason codes |
+| ITMS-91055 | Invalid reason code for a declared API category | Replace with a valid reason code from Apple's predefined list |
+| ITMS-91056 | Malformed or invalid privacy manifest file | Validate plist XML structure; re-create via Xcode template |
+| ITMS-91061 | A third-party SDK is missing its privacy manifest | Update the SDK or add a manifest to its bundle |
+
+**TestFlight catches these errors** — always run a TestFlight build before production submission.
+
+Other common pitfalls:
+- Declaring `NSPrivacyTracking = true` but omitting `NSUserTrackingUsageDescription` in `Info.plist`.
+- Using reason code `CA92.1` (app-only) when the app actually shares `UserDefaults` via App Group — use `1C8F.1` instead.
+- Forgetting to declare `NSPrivacyAccessedAPICategoryFileTimestamp` when using `SDWebImage`, `Kingfisher`, or other caching libraries that call `stat()`.
+- Declaring collected data types without matching entries in the App Store Connect privacy questionnaire.
+
+## 7. Complete example
+
+A typical app using `UserDefaults`, file timestamps (caching), and analytics with crash reporting:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+
+  <!-- Tracking -->
+  <key>NSPrivacyTracking</key>
+  <false/>
+  <key>NSPrivacyTrackingDomains</key>
+  <array/>
+
+  <!-- Collected data types -->
+  <key>NSPrivacyCollectedDataTypes</key>
+  <array>
+    <!-- Crash data for stability monitoring -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeCrashData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+      </array>
+    </dict>
+    <!-- Performance metrics -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypePerformanceData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+    <!-- User ID for account features -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeUserID</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+      </array>
+    </dict>
+  </array>
+
+  <!-- Required reason APIs -->
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <!-- UserDefaults: app-only storage -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>CA92.1</string>
+      </array>
+    </dict>
+    <!-- File timestamps: cache management -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>C617.1</string>
+      </array>
+    </dict>
+    <!-- System boot time: elapsed time measurement -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>35F9.1</string>
+      </array>
+    </dict>
+  </array>
+
+</dict>
+</plist>
+```
+
+### Variant: app with App Group sharing and tracking
+
+If the app shares data with a widget via App Group and uses an ad SDK:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+
+  <key>NSPrivacyTracking</key>
+  <true/>
+  <key>NSPrivacyTrackingDomains</key>
+  <array>
+    <string>analytics.example.com</string>
+    <string>ads.example.com</string>
+  </array>
+
+  <key>NSPrivacyCollectedDataTypes</key>
+  <array>
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeDeviceID</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising</string>
+      </array>
+    </dict>
+  </array>
+
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>CA92.1</string>
+        <string>1C8F.1</string>
+      </array>
+    </dict>
+  </array>
+
+</dict>
+</plist>
+```
+
+Note: when `NSPrivacyTracking` is `true`, the app must also declare `NSUserTrackingUsageDescription` in `Info.plist` and call `ATTrackingManager.requestTrackingAuthorization()` before any tracking occurs.
+
+## Decision checklist
+
+Before generating the manifest, answer these:
+
+1. Does the app use `UserDefaults`? (almost always yes) --> `CA92.1` or `1C8F.1`
+2. Does the app or any dependency read file timestamps? (caching libraries do) --> `C617.1`
+3. Does the app measure elapsed time or call `mach_absolute_time()`? --> `35F9.1`
+4. Does the app check disk space before writes? --> `E174.1`
+5. Does the app inspect active keyboards? (rare) --> `54BD.1`
+6. Does the app collect crash/performance data? --> add collected data type entries
+7. Does the app link data to user identity? --> set `Linked` to `true` on those types
+8. Does the app track users for advertising? --> `NSPrivacyTracking = true` + ATT + tracking domains

package/skills/ios/hig-components-content/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: hig-components-content
+version: 1.0.0
+description: >-
+  Apple Human Interface Guidelines for content display components. Use this skill when the user asks about
+  "charts component", "collection view", "image view", "web view", "color well", "image well",
+  "activity view", "lockup", "data visualization", "content display", displaying images, rendering
+  web content, color pickers, or presenting collections of items in Apple apps.
+  Also use when the user says "how should I display charts", "what's the best way to show images",
+  "should I use a web view", "how do I build a grid of items", "what component shows media",
+  or "how do I present a share sheet".
+  Cross-references: hig-foundations for color/typography/accessibility, hig-patterns for data
+  visualization patterns, hig-components-layout for structural containers, hig-platforms for
+  platform-specific component behavior.
+---
+
+# Apple HIG: Content Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Adapt to different sizes and contexts.** Content components must work across screen sizes, orientations, and multitasking configurations. Use Auto Layout and size classes.
+
+2. **Make content accessible.** Charts need audio graph support. Images need alt text. Collections need proper VoiceOver navigation order. All content components need labels and descriptions.
+
+3. **Maintain visual hierarchy.** Use spacing, sizing, and grouping to establish clear information hierarchy. Primary content should be visually prominent.
+
+4. **Use system components first.** Evaluate UICollectionView, SwiftUI Charts, WKWebView before building custom. System components come with built-in accessibility and platform adaptation.
+
+5. **Respect platform conventions.** A collection on tvOS uses large lockups with parallax. The same collection on iOS uses compact cells with touch targets. On visionOS, content gains depth and hover effects.
+
+6. **Handle empty states.** Show a meaningful empty state with guidance on how to populate it, not a blank screen.
+
+7. **Optimize for performance.** Use lazy loading, cell reuse, pagination, and prefetching for large datasets.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [charts.md](references/charts.md) | Charts | Swift Charts, bar/line/area/point marks, chart accessibility, audio graphs |
+| [collections.md](references/collections.md) | Collections | Grid/list layouts, compositional layout, selection, reordering, diffable data sources |
+| [image-views.md](references/image-views.md) | Image Views | Aspect ratio handling, content modes, SF Symbol images, accessibility |
+| [image-wells.md](references/image-wells.md) | Image Wells | Drag-and-drop image selection, macOS-specific, placeholder content |
+| [color-wells.md](references/color-wells.md) | Color Wells | Color selection UI, system color picker, custom color spaces |
+| [web-views.md](references/web-views.md) | Web Views | WKWebView, SFSafariViewController, navigation controls, content restrictions |
+| [activity-views.md](references/activity-views.md) | Activity Views | Share sheets, activity items, custom activities, action extensions |
+| [lockups.md](references/lockups.md) | Lockups | Image+text elements, tvOS card layouts, focus effects, shelf layouts |
+
+## Component Selection Guide
+
+| Content Need | Recommended Component | Platform Notes |
+|---|---|---|
+| Visualizing quantitative data | Charts (Swift Charts) | iOS 16+, macOS 13+, watchOS 9+ |
+| Browsing a grid or list of items | Collection View | Compositional layout for complex arrangements |
+| Displaying a single image | Image View | Support aspect ratio fitting; provide accessibility description |
+| Selecting an image via drag or browse | Image Well | macOS primarily; use image pickers on iOS |
+| Selecting a color | Color Well | Triggers system color picker; macOS, iOS 14+ |
+| Showing web content inline | Web View (WKWebView) | Use SFSafariViewController for external browsing |
+| Sharing content to other apps | Activity View | System share sheet with configurable activity types |
+| Content card (image + text) | Lockup | Primarily tvOS; adaptable to other platforms |
+
+## Output Format
+
+1. **Component recommendation with rationale**, referencing the relevant HIG reference file.
+2. **Configuration guidance** -- key properties and setup.
+3. **Accessibility requirements** for the recommended component.
+4. **Platform-specific notes** for targeted platforms.
+
+## Questions to Ask
+
+1. What type of content? (Quantitative data, images, web content, browsable collection, share action?)
+2. Which platforms?
+3. Static or dynamic content?
+4. How much content? (Few items vs hundreds/thousands affects component choice and optimization.)
+
+## Related Skills
+
+- **hig-foundations** -- Color, typography, accessibility, and image guidelines
+- **hig-patterns** -- Data visualization, sharing, and loading patterns
+- **hig-components-layout** -- Structural containers (scroll views, lists, split views) hosting content
+- **hig-platforms** -- Platform-specific component behavior (lockups on tvOS, web views on macOS)
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*