docs: add sharing system overhaul design
Complete redesign of sharing to support: - Trip summary cards with route maps - 4 achievement card types (spotlight, collection, milestone, context) - Stadium progress cards - 8 user-customizable color themes - Instagram Stories as primary target (1080×1920) - Contextual share buttons throughout app Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Trey t
430
docs/plans/2026-01-13-sharing-overhaul-design.md
Normal file
430
docs/plans/2026-01-13-sharing-overhaul-design.md
Normal file
@@ -0,0 +1,430 @@
|
|||||||
|
# Sharing System Overhaul
|
||||||
|
|
||||||
|
*Design finalized: January 13, 2026*
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Complete overhaul of the sharing system to support shareable cards for trip summaries, achievements, and stadium progress. Primary target is Instagram Stories (1080×1920 vertical cards) with user-customizable color themes.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
- Share trip summaries as visual cards (not just deep links)
|
||||||
|
- Share achievements (single, collection, milestone, contextual)
|
||||||
|
- Share stadium progress with map visualization
|
||||||
|
- User-customizable color themes (8 presets)
|
||||||
|
- Contextual share buttons throughout the app (low friction)
|
||||||
|
- Instagram Stories as primary destination
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Protocol-Based Design
|
||||||
|
|
||||||
|
All shareable content types conform to a common protocol:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
protocol ShareableContent {
|
||||||
|
var cardType: ShareCardType { get }
|
||||||
|
func render(theme: ShareTheme) async throws -> UIImage
|
||||||
|
}
|
||||||
|
|
||||||
|
enum ShareCardType {
|
||||||
|
case tripSummary
|
||||||
|
case achievementSpotlight
|
||||||
|
case achievementCollection
|
||||||
|
case achievementMilestone
|
||||||
|
case achievementContext
|
||||||
|
case stadiumProgress
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Hierarchy
|
||||||
|
|
||||||
|
```
|
||||||
|
ShareableContent (protocol)
|
||||||
|
├── TripShareContent → TripCardGenerator
|
||||||
|
├── AchievementShareContent → AchievementCardGenerator
|
||||||
|
├── ProgressShareContent → ProgressCardGenerator
|
||||||
|
└── CollectionShareContent → CollectionCardGenerator
|
||||||
|
```
|
||||||
|
|
||||||
|
### Unified Components
|
||||||
|
|
||||||
|
- `ShareTheme` - Color preset definitions
|
||||||
|
- `ShareCardFooter` - Reusable SportsTime branding footer
|
||||||
|
- `ShareCardHeader` - Sport icon + title treatment
|
||||||
|
- `ShareService` - Instagram URL scheme, image export, fallback share sheet
|
||||||
|
|
||||||
|
## Theme System
|
||||||
|
|
||||||
|
### 8 Color Presets
|
||||||
|
|
||||||
|
| Theme | Background Gradient | Accent | Text | Use Case |
|
||||||
|
|-------|---------------------|--------|------|----------|
|
||||||
|
| **Dark** | #1A1A2E → #16213E | #FF6B35 | White | Default, premium feel |
|
||||||
|
| **Light** | #FFFFFF → #F5F5F5 | #FF6B35 | #1A1A2E | Clean, minimal |
|
||||||
|
| **Midnight** | #0D1B2A → #1B263B | #00D4FF | White | Night game energy |
|
||||||
|
| **Forest** | #1B4332 → #2D6A4F | #95D5B2 | White | Baseball/outdoor |
|
||||||
|
| **Sunset** | #FF6B35 → #F7931E | #FFFFFF | White | Bold, attention-grabbing |
|
||||||
|
| **Berry** | #4A0E4E → #81267E | #FF85A1 | White | Unique, stands out |
|
||||||
|
| **Ocean** | #023E8A → #0077B6 | #90E0EF | White | Cool, professional |
|
||||||
|
| **Slate** | #2B2D42 → #3D405B | #F4A261 | #EDF2F4 | Sophisticated neutral |
|
||||||
|
|
||||||
|
### Theme Definition
|
||||||
|
|
||||||
|
```swift
|
||||||
|
struct ShareTheme: Identifiable, Hashable {
|
||||||
|
let id: String
|
||||||
|
let name: String
|
||||||
|
let gradientColors: [Color]
|
||||||
|
let accentColor: Color
|
||||||
|
let textColor: Color
|
||||||
|
let secondaryTextColor: Color
|
||||||
|
let mapStyle: MapStyle // .light or .dark
|
||||||
|
|
||||||
|
static let all: [ShareTheme] = [.dark, .light, .midnight, .forest, .sunset, .berry, .ocean, .slate]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Theme preference is persisted per content type via UserDefaults.
|
||||||
|
|
||||||
|
## Card Designs
|
||||||
|
|
||||||
|
### Card Dimensions
|
||||||
|
|
||||||
|
All cards use Instagram Story dimensions: **1080 × 1920 pixels** (9:16 aspect ratio).
|
||||||
|
|
||||||
|
### Trip Summary Card
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ [Sport Icon] │ ← Header: 120px
|
||||||
|
│ "My Baseball Road Trip" │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────┐ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ MAP SNAPSHOT │ │ ← Hero map: 600px
|
||||||
|
│ │ with route line │ │ Route drawn in accent color
|
||||||
|
│ │ + city markers │ │ Visited cities = filled dots
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ "Jun 15 - Jun 22, 2026" │ ← Date range
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌───────┐ ┌───────┐ ┌───────┐ │
|
||||||
|
│ │ 1,847 │ │ 5 │ │ 4 │ │ ← Stats row
|
||||||
|
│ │ miles │ │ games │ │cities │ │
|
||||||
|
│ └───────┘ └───────┘ └───────┘ │
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ Chicago → Milwaukee → Detroit │ ← City trail
|
||||||
|
│ → Cleveland → Pittsburgh │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ [SportsTime logo] │ ← Footer: 100px
|
||||||
|
│ "Plan your stadium adventure" │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Map Features:**
|
||||||
|
- Route line drawn using MKPolyline in accent color
|
||||||
|
- City markers: filled circles with abbreviation labels
|
||||||
|
- Map style matches theme (muted standard for dark themes)
|
||||||
|
|
||||||
|
### Achievement Cards
|
||||||
|
|
||||||
|
#### Type 1: Single Spotlight
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
│ ┌───────────┐ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ BADGE │ │ ← Large badge: 400×400px
|
||||||
|
│ │ GRAPHIC │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └───────────┘ │
|
||||||
|
│ │
|
||||||
|
│ "ALL NL WEST" │ ← Achievement name
|
||||||
|
│ │
|
||||||
|
│ "Visited all 5 stadiums │ ← Description
|
||||||
|
│ in the National League │
|
||||||
|
│ West division" │
|
||||||
|
│ │
|
||||||
|
│ ✓ Unlocked Jan 12, 2026 │ ← Unlock date
|
||||||
|
│ │
|
||||||
|
│ [SportsTime logo + tagline] │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Type 2: Collection Grid
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ "My 2026 Achievements" │ ← Header with year
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ ┌─────┐ ┌─────┐ ┌─────┐ │
|
||||||
|
│ │Badge│ │Badge│ │Badge│ │ ← 3×3 or 3×4 grid
|
||||||
|
│ │ #1 │ │ #2 │ │ #3 │ │
|
||||||
|
│ └─────┘ └─────┘ └─────┘ │
|
||||||
|
│ ┌─────┐ ┌─────┐ ┌─────┐ │
|
||||||
|
│ │Badge│ │Badge│ │Badge│ │
|
||||||
|
│ │ #4 │ │ #5 │ │ #6 │ │
|
||||||
|
│ └─────┘ └─────┘ └─────┘ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ "12 achievements unlocked" │ ← Summary count
|
||||||
|
│ [SportsTime logo + tagline] │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Type 3: Milestone Celebration
|
||||||
|
|
||||||
|
Same as Single Spotlight with:
|
||||||
|
- Animated particle/confetti burst pattern (static for image)
|
||||||
|
- Larger badge (500×500px)
|
||||||
|
- "MILESTONE" label above badge
|
||||||
|
- Gold accent elements regardless of theme
|
||||||
|
|
||||||
|
#### Type 4: Achievement + Context
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ ┌─────────┐ │
|
||||||
|
│ │ BADGE │ "Coast to Coast" │ ← Badge + name side by side
|
||||||
|
│ └─────────┘ Unlocked! │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────┐ │
|
||||||
|
│ │ TRIP MAP or │ │ ← Context: trip/visit
|
||||||
|
│ │ STADIUM PHOTO │ │ that unlocked it
|
||||||
|
│ └─────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ "Unlocked during my │
|
||||||
|
│ Summer 2026 Road Trip" │ ← Trip name or visit date
|
||||||
|
│ │
|
||||||
|
│ [SportsTime logo + tagline] │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Stadium Progress Card
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ [Sport Icon] │
|
||||||
|
│ "MLB Stadium Quest" │ ← Header
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌───────────┐ │
|
||||||
|
│ ╱ ╲ │
|
||||||
|
│ │ 18 │ │ ← Progress ring: 320px
|
||||||
|
│ │ ──── │ │ Accent color fill
|
||||||
|
│ │ of 30 │ │
|
||||||
|
│ ╲ ╱ │
|
||||||
|
│ └───────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 60% Complete │ ← Percentage
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ ┌───────┐ ┌───────┐ ┌───────┐ │
|
||||||
|
│ │ 18 │ │ 12 │ │ 4 │ │ ← Stats row
|
||||||
|
│ │visited│ │remain │ │trips │ │
|
||||||
|
│ └───────┘ └───────┘ └───────┘ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ ┌─────────────────────┐ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ US MAP SNAPSHOT │ │ ← Map: 500px height
|
||||||
|
│ │ ● visited (accent)│ │
|
||||||
|
│ │ ○ remaining (gray)│ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────┘ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ @username (optional) │ ← Optional username
|
||||||
|
│ [SportsTime logo + tagline] │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Share UI/UX
|
||||||
|
|
||||||
|
### Contextual Share Buttons
|
||||||
|
|
||||||
|
`ShareButton` component appears on:
|
||||||
|
- Trip cards in saved trips list
|
||||||
|
- Trip detail view toolbar
|
||||||
|
- Achievement badges (on tap)
|
||||||
|
- Progress ring on Progress tab
|
||||||
|
- Achievement list header (for collection)
|
||||||
|
|
||||||
|
```swift
|
||||||
|
struct ShareButton: View {
|
||||||
|
let content: ShareableContent
|
||||||
|
@State private var showPreview = false
|
||||||
|
|
||||||
|
var body: some View {
|
||||||
|
Button {
|
||||||
|
showPreview = true
|
||||||
|
} label: {
|
||||||
|
Image(systemName: "square.and.arrow.up")
|
||||||
|
}
|
||||||
|
.sheet(isPresented: $showPreview) {
|
||||||
|
SharePreviewView(content: content)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### SharePreviewView
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ ← Cancel Share → │ ← Nav bar
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────┐ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ LIVE PREVIEW │ │ ← 40% scale preview
|
||||||
|
│ │ of card │ │ Updates in real-time
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ Theme │
|
||||||
|
│ [Dark] [Light] [Midnight] ... │ ← Horizontal scroll
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ ☑ Include username │ ← Toggle (progress only)
|
||||||
|
│ [@yourhandle____________] │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────┐ │
|
||||||
|
│ │ Share to Instagram │ │ ← Primary CTA
|
||||||
|
│ └─────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ [Copy Image] [More Options] │ ← Secondary actions
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instagram Integration
|
||||||
|
|
||||||
|
```swift
|
||||||
|
func shareToInstagram(image: UIImage) {
|
||||||
|
guard let imageData = image.pngData() else { return }
|
||||||
|
|
||||||
|
// Write to shared container for Instagram
|
||||||
|
let pasteboardItems: [String: Any] = [
|
||||||
|
"com.instagram.sharedSticker.backgroundImage": imageData
|
||||||
|
]
|
||||||
|
|
||||||
|
UIPasteboard.general.setItems([pasteboardItems])
|
||||||
|
|
||||||
|
// Open Instagram Stories
|
||||||
|
if let url = URL(string: "instagram-stories://share?source_application=com.sportstime.app") {
|
||||||
|
UIApplication.shared.open(url)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Falls back to standard `UIActivityViewController` if Instagram not installed.
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
### Files to Delete
|
||||||
|
|
||||||
|
| File | Lines |
|
||||||
|
|------|-------|
|
||||||
|
| `SportsTime/Export/Services/ProgressCardGenerator.swift` | 607 |
|
||||||
|
|
||||||
|
### New Files
|
||||||
|
|
||||||
|
| File | Purpose | ~Lines |
|
||||||
|
|------|---------|--------|
|
||||||
|
| `Export/Sharing/ShareableContent.swift` | Protocol + ShareTheme | 120 |
|
||||||
|
| `Export/Sharing/ShareCardComponents.swift` | Header, footer, stats, map | 200 |
|
||||||
|
| `Export/Sharing/TripCardGenerator.swift` | Trip summary cards | 180 |
|
||||||
|
| `Export/Sharing/AchievementCardGenerator.swift` | All 4 achievement types | 350 |
|
||||||
|
| `Export/Sharing/ProgressCardGenerator.swift` | Stadium progress cards | 180 |
|
||||||
|
| `Export/Sharing/ShareService.swift` | Instagram, export, share sheet | 150 |
|
||||||
|
| `Export/Views/SharePreviewView.swift` | Unified preview UI | 250 |
|
||||||
|
| `Export/Views/ShareButton.swift` | Contextual button | 40 |
|
||||||
|
|
||||||
|
### Files to Modify
|
||||||
|
|
||||||
|
| File | Changes |
|
||||||
|
|------|---------|
|
||||||
|
| `TripDetailView.swift` | Replace `shareTrip()` with `ShareButton`, remove old `ShareSheet` |
|
||||||
|
| `ProgressTabView.swift` | Add `ShareButton` to progress rings |
|
||||||
|
| Achievement views | Add `ShareButton` to badges |
|
||||||
|
|
||||||
|
## Implementation Notes
|
||||||
|
|
||||||
|
### Map Snapshot Generation
|
||||||
|
|
||||||
|
Reuse pattern from existing code but extract to `ShareCardComponents`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
func generateRouteMapSnapshot(
|
||||||
|
stops: [TripStop],
|
||||||
|
theme: ShareTheme
|
||||||
|
) async -> UIImage? {
|
||||||
|
// Calculate bounding region
|
||||||
|
// Configure MKMapSnapshotter with theme-appropriate style
|
||||||
|
// Draw route polyline in accent color
|
||||||
|
// Draw city markers
|
||||||
|
}
|
||||||
|
|
||||||
|
func generateProgressMapSnapshot(
|
||||||
|
visited: [Stadium],
|
||||||
|
remaining: [Stadium],
|
||||||
|
theme: ShareTheme
|
||||||
|
) async -> UIImage? {
|
||||||
|
// Calculate US-wide region
|
||||||
|
// Draw visited markers in accent color
|
||||||
|
// Draw remaining markers in gray
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Image Rendering
|
||||||
|
|
||||||
|
Use SwiftUI `ImageRenderer` at 3x scale for high-res output:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
func render(theme: ShareTheme) async throws -> UIImage {
|
||||||
|
let cardView = TripCardView(trip: trip, theme: theme)
|
||||||
|
let renderer = ImageRenderer(content: cardView)
|
||||||
|
renderer.scale = 3.0
|
||||||
|
|
||||||
|
guard let image = renderer.uiImage else {
|
||||||
|
throw ShareError.renderingFailed
|
||||||
|
}
|
||||||
|
return image
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Theme Persistence
|
||||||
|
|
||||||
|
```swift
|
||||||
|
@AppStorage("shareTheme.trip") private var tripThemeId: String = "dark"
|
||||||
|
@AppStorage("shareTheme.achievement") private var achievementThemeId: String = "dark"
|
||||||
|
@AppStorage("shareTheme.progress") private var progressThemeId: String = "dark"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Scope Summary
|
||||||
|
|
||||||
|
| Category | Count |
|
||||||
|
|----------|-------|
|
||||||
|
| New lines | ~1,470 |
|
||||||
|
| Deleted lines | ~607 |
|
||||||
|
| Modified lines | ~50 |
|
||||||
|
| New files | 8 |
|
||||||
|
| Deleted files | 1 |
|
||||||
|
| Modified files | 3+ |
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
- [ ] All 3 content types shareable (trips, achievements, progress)
|
||||||
|
- [ ] All 8 theme presets working
|
||||||
|
- [ ] Instagram Stories direct share working
|
||||||
|
- [ ] Fallback to share sheet when Instagram not installed
|
||||||
|
- [ ] Share buttons appear contextually throughout app
|
||||||
|
- [ ] Theme preference persisted per content type
|
||||||
|
- [ ] Cards render at 1080×1920 with proper scaling
|
||||||
Reference in New Issue
Block a user