buildanything 1.8.0 → 2.0.0

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)*

package/skills/ios/hig-components-content/references/activity-views.md

@@ -0,0 +1,79 @@
+---
+title: "Activity views | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/activity-views
+
+# Activity views
+
+An activity view — often called a _share sheet_ — presents a range of tasks that people can perform in the current context.
+
+![A stylized representation of an activity view or share sheet. The image is tinted red to subtly reflect the red in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/74899abd7c2a017fc05523d112743616/components-activity-view-intro%402x.png)
+
+Activity views present sharing activities like messaging and actions like Copy and Print, in addition to quick access to frequently used apps. People typically reveal a share sheet by choosing an Action button while viewing a page or document, or after they’ve selected an item. An activity view can appear as a sheet or a popover, depending on the device and orientation.
+
+You can provide app-specific activities that can appear in a share sheet when people open it within your app or game. For example, Photos provides app-specific actions like Copy Photo, Add to Album, and Adjust Location. By default, the system lists app-specific actions before actions — such as Add to Files or AirPlay — that are available in multiple apps or throughout the system. People can edit the list of actions to ensure that it displays the ones they use most and to add new ones.
+
+You can also create app extensions to provide custom share and action activities that people can use in other apps. (An _app extension_ is code you provide that people can install and use outside of your app.) For example, you might create a custom share activity that people can install to help them share a webpage with a specific social media service. Even though macOS doesn’t provide an activity view, you can create share and action app extensions that people can use on a Mac. For guidance, see [Share and action extensions](https://developer.apple.com/design/human-interface-guidelines/activity-views#Share-and-action-extensions).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/activity-views#Best-practices)
+
+**Avoid creating duplicate versions of common actions that are already available in the activity view.** For example, providing a duplicate Print action is unnecessary and confusing because people wouldn’t know how to distinguish your action from the system-provided one. If you need to provide app-specific functionality that’s similar to an existing action, give it a custom title. For example, if you let people use custom formatting to print a bank transaction, use a title that helps people understand what your print activity does, like “Print Transaction.”
+
+**Consider using a symbol to represent your custom activity.** [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) provides a comprehensive set of configurable symbols you can use to communicate items and concepts in an activity view. If you need to create a custom interface icon, center it in an area measuring about 70x70 pixels. For guidance, see [Icons](https://developer.apple.com/design/human-interface-guidelines/icons).
+
+**Write a succinct, descriptive title for each custom action you provide.** If a title is too long, the system wraps it and may truncate it. Prefer a single verb or a brief verb phrase that clearly communicates what the action does. Avoid including your company or product name in an action title. In contrast, the share sheet displays the title of a share activity — typically a company name — below the icon that represents it.
+
+**Make sure activities are appropriate for the current context.** Although you can’t reorder system-provided tasks in an activity view, you can exclude tasks that aren’t applicable to your app. For example, if it doesn’t make sense to print from within your app, you can exclude the Print activity. You can also identify which custom tasks to show at any given time.
+
+**Use the Share button to display an activity view.** People are accustomed to accessing system-provided activities when they choose the Share button. Avoid confusing people by providing an alternative way to do the same thing.
+
+![A screenshot of the Notes app on iPhone, with an open Notes document titled Nature Walks. The top toolbar includes a Share button grouped with a More button on its trailing edge.](https://docs-assets.developer.apple.com/published/5cdc980290422f59da0f79ab5f5efd13/activity-views-share-button%402x.png)
+
+![A screenshot of the Notes app on iPhone, with an open Notes document titled Nature Walks. An activity view is open from the Share button, including controls for sharing the document with contacts or other apps, and copying, exporting, or adding markup to the document.](https://docs-assets.developer.apple.com/published/68a789fa9a70048fcef600615af180fd/activity-views-share-sheet%402x.png)
+
+## [Share and action extensions](https://developer.apple.com/design/human-interface-guidelines/activity-views#Share-and-action-extensions)
+
+Share extensions give people a convenient way to share information from the current context with apps, social media accounts, and other services. Action extensions let people initiate content-specific tasks — like adding a bookmark, copying a link, editing an inline image, or displaying selected text in another language — without leaving the current context.
+
+The system presents share and action extensions differently depending on the platform:
+
+  * In iOS and iPadOS, share and action extensions are displayed in the share sheet that appears when people choose an Action button.
+
+  * In macOS, people access share extensions by clicking a Share button in the toolbar or choosing Share in a context menu. People can access an action extension by holding the pointer over certain types of embedded content — like an image they add to a Mail compose window — clicking a toolbar button, or choosing a quick action in a Finder window.
+
+
+
+
+**If necessary, create a custom interface that feels familiar to people.** For a share extension, prefer the system-provided composition view because it provides a consistent sharing experience that people already know. For an action extension, include your app name. If you need to present an interface, include elements of your app’s interface to help people understand that your extension and your app are related.
+
+**Streamline and limit interaction.** People appreciate extensions that let them perform a task in just a few steps. For example, a share extension might immediately post an image to a social media account with a single tap or click.
+
+**Avoid placing a modal view above your extension.** By default, the system displays an extension within a modal view. While it might be necessary to display an alert above an extension, avoid displaying additional modal views.
+
+**If necessary, provide an image that communicates the purpose of your extension.** A share extension automatically uses your app icon, helping give people confidence that your app provided the extension. For an action extension, prefer using a [symbol](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) or creating an interface [icon](https://developer.apple.com/design/human-interface-guidelines/icons) that clearly identifies the task.
+
+**Use your main app to denote the progress of a lengthy operation.** An activity view dismisses immediately after people complete the task in your share or action extension. If a task is time-consuming, continue it in the background, and give people a way to check the status in your main app. Although you can use a notification to tell people about a problem, don’t notify them simply because the task completes.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/activity-views#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or visionOS. Not supported in macOS, tvOS, or watchOS._
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/activity-views#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/activity-views#Related)
+
+[Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets)
+
+[Popovers](https://developer.apple.com/design/human-interface-guidelines/popovers)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/activity-views#Developer-documentation)
+
+[`UIActivityViewController`](https://developer.apple.com/documentation/UIKit/UIActivityViewController) — UIKit
+
+[`UIActivity`](https://developer.apple.com/documentation/UIKit/UIActivity) — UIKit
+
+[App Extension Support](https://developer.apple.com/documentation/Foundation/app-extension-support) — Foundation
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/activity-views#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/74342B30-92E9-48F3-B0F2-6E42C8FD9391/6506_wide_250x141_1x.jpg) Design for Collaboration with Messages ](https://developer.apple.com/videos/play/wwdc2022/10015)
+