Fix iOS patterns: prefer SwiftUI, add xcodegen project setup, fix token approach

[mattpodwysocki]

Summary

Fixes gaps discovered while building a real demo iOS app with the Mapbox Maps SDK v11. The skill was producing incorrect patterns — particularly recommending bare SPM packages (which can't run as iOS apps) and missing most of the SwiftUI-native annotation API.

• Project setup: Add xcodegen + project.yml pattern. A bare SPM .target builds as a library — it cannot launch as an iOS app. This was the biggest practical gap.
• Token: Add Config.swift + MapboxOptions.accessToken approach for SPM/xcodegen projects alongside the existing Info.plist approach (which only works in Xcode-managed projects)
• SwiftUI first: Explicitly discourage UIViewRepresentable wrappers; Map(viewport:) is the correct SwiftUI entry point
• Annotations: Add CircleAnnotationGroup, PointAnnotationGroup, .onTapGesture per annotation, and MapViewAnnotation for callouts — all missing from the SwiftUI section
• Camera animation: Add withViewportAnimation(.fly(duration:)) for SwiftUI (the UIKit mapView.camera.fly(to:) was the only documented pattern)
• User location: Add Puck2D(bearing: .heading) inside Map {} for SwiftUI
• StyleColor gotcha: Document that StyleColor(red:green:blue:alpha:) returns optional — use StyleColor(UIColor(...)) instead
• StyleURI: Clarify rawValue: for mapbox:// URIs vs url: for https:// URLs
• Minimum iOS: Bump recommendation from iOS 12 to iOS 16 with explanation (NavigationSplitView requires 16, foregroundStyle requires 15)
• Evals: Update token eval (Add mapbox-geospatial-operations skill #1), add 4 new evals covering project setup, SwiftUI annotation groups, camera animation, and StyleColor optional

Eval fixes (cross-skill, added in latest commit)

Ran a full eval suite across all 18 skills and fixed the worst-scoring gaps:

Skill	Before	After
mapbox-style-quality	67%	93%
mapbox-search-integration	75%	100%
mapbox-style-patterns	80%	100%
mapbox-ios-patterns	83%	95%

Changes:

• ios-patterns AGENTS.md: add XcodeGen gitignore guidance (project.yml committed, .xcodeproj gitignored); fix stale .iconImage() → .image(.init(image:name:))
• search-integration SKILL.md: add Custom UI section surfacing session token requirement for direct API callers (billing impact)
• style-patterns references/data-viz-base.md: explain why water must be gray not blue for choropleth maps (blue water competes with red/blue election data)
• style-quality SKILL.md: expand Large Style File Size troubleshooting to spell out ordered cleanup steps (empty layers, boolean expressions) and reviewing percentReduction/changes in the optimization report

Test plan

• npm run eval mapbox-ios-patterns — 7/7 pass (95%)
• npm run eval mapbox-search-integration — 3/3 pass (100%)
• npm run eval mapbox-style-patterns — 3/3 pass (100%)
• npm run eval mapbox-style-quality — 3/3 pass (93%)
• xcodegen generate produces a working .xcodeproj from the documented project.yml
• SwiftUI annotation patterns compile against MapboxMaps 11.x

🤖 Generated with Claude Code