# 28. iOS App — SwiftUI Foundation, Navigation, and Shared Theme

meta:
  id: shieldai-unified-restructure-28
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-01, shieldai-unified-restructure-02]
  tags: [ios, swiftui, foundation, navigation, mobile]

objective:
- Establish the iOS app foundation in `iOS/ShieldAI/`: a SwiftUI project with app entry point, navigation architecture, and a shared theme system that mirrors the web app's ShieldAI brand palette and auto-shifting dark mode.

deliverables:
- `iOS/ShieldAI/ShieldAIApp.swift` — App entry point:
  - `@main` app struct with `WindowGroup`
  - Initializes dependency container (if using DI)
  - Sets up appearance (tint color, navigation bar style)
- `iOS/ShieldAI/ContentView.swift` — Root view:
  - `TabView` with 5 tabs: Dashboard, Services, Alerts, Settings, Account
  - Or `NavigationStack` with sidebar for iPad
  - Handles auth state: shows `AuthView` if unauthenticated, `MainView` if authenticated
- `iOS/ShieldAI/Navigation/` — Navigation infrastructure:
  - `AppRouter.swift` — Navigation path manager using `NavigationPath`
  - `Route.swift` — Enum of all app routes with associated values
  - `RouterViewModifier.swift` — View modifier for deep linking
- `iOS/ShieldAI/Theme/` — Shared theme system:
  - `ShieldAITheme.swift` — Theme protocol/struct with colors, fonts, spacing
  - `Color+ShieldAI.swift` — SwiftUI Color extensions for all brand tokens:
    - `brandPrimary`, `brandPrimaryLight`, `brandPrimaryDark`
    - `brandAccent`, `brandAccentLight`, `brandAccentDark`
    - `bgPrimary`, `bgSecondary`, `bgTertiary`
    - `textPrimary`, `textSecondary`, `textTertiary`
    - `border`, `success`, `warning`, `error`
  - `Font+ShieldAI.swift` — Typography scale matching web app
  - `ThemeManager.swift` — Observable object managing light/dark/system mode
- `iOS/ShieldAI/Info.plist` and `Assets.xcassets/`:
  - App icon set (reuse web app SVGs converted to PNG/AppIcon)
  - Color assets for dynamic light/dark variants
  - Launch screen storyboard or SwiftUI launch view
- Project configuration:
  - Xcode project or Swift Package Manager setup
  - Minimum iOS version: 16.0 (SwiftUI 2.0+ features, NavigationStack)
  - Target devices: iPhone + iPad

steps:
1. Verify `iOS/ShieldAI/` exists and has a valid Xcode project or Package.swift.
2. Create `ShieldAIApp.swift`:
   - Set global accent color to `brandPrimary`
   - Configure navigation bar appearance
   - Inject `ThemeManager` as environment object
3. Create `ContentView.swift`:
   - Use `@StateObject` for auth state
   - If unauthenticated: present full-screen `AuthView` (task 30)
   - If authenticated: show `TabView` with tabs
4. Create navigation system:
   - `Route` enum with cases: `.dashboard`, `.service(ShieldService)`, `.alertDetail(Alert)`, `.settings`, `.profile`, etc.
   - `AppRouter` class with `NavigationPath` and `navigate(to:)`, `pop()`, `popToRoot()`
   - Support deep linking via URL scheme (`shieldai://dashboard`, `shieldai://alert/123`)
5. Create theme system:
   - Define all colors as static properties on `Color` extension
   - Use `UIColor` dynamic colors for light/dark variants:
     ```swift
     static let bgPrimary = Color(UIColor { traitCollection in
       traitCollection.userInterfaceStyle == .dark ? UIColor(hex: "#111827") : UIColor(hex: "#fafbfc")
     })
     ```
   - Define font scale: `.caption`, `.body`, `.headline`, `.title`, `.largeTitle`
   - Define spacing scale: `.xs` (4), `.sm` (8), `.md` (16), `.lg` (24), `.xl` (32), `.xxl` (48)
6. Create `ThemeManager.swift`:
   - `@Published var colorScheme: ColorScheme?` (nil = system)
   - Methods: `setLight()`, `setDark()`, `setSystem()`
   - Persist preference in `UserDefaults`
   - Apply to root view using `.preferredColorScheme()`
7. Set up assets:
   - Convert ShieldAI logo SVG to PDF or PNG for Xcode assets
   - Create color assets for all theme tokens with "Any, Dark" variants
   - Add AppIcon set for all required sizes
8. Build and run on iOS Simulator to verify app launches with correct theme.

steps:
- Unit: ThemeManager correctly toggles between light/dark/system
- Unit: Color extensions return correct values for light and dark traits
- Unit: AppRouter pushes and pops routes correctly
- Visual: App launches with ShieldAI branding and correct tab structure
- Visual: Theme shifts correctly when device dark mode toggles

acceptance_criteria:
- [ ] iOS app launches without crashes on iPhone and iPad simulators
- [ ] Tab navigation has 5 tabs with correct icons and labels
- [ ] Theme colors match web app palette in both light and dark modes
- [ ] Theme manager persists user preference across app restarts
- [ ] Navigation stack works for pushing and popping views
- [ ] Deep linking supports `shieldai://` URL scheme
- [ ] App icon and launch screen display correctly

validation:
- Build and run on iPhone 15 Pro simulator (iOS 17+)
- Toggle device dark mode and verify all colors shift
- Test navigation by tapping through all tabs and sub-pages
- Verify deep link: `xcrun simctl openurl booted shieldai://dashboard`
- Run unit tests via Xcode Cmd+U

notes:
- The iOS app should feel like a native sibling to the web app, not a port. Use native iOS patterns (tab bar, navigation bar, sheets, context menus).
- SwiftUI's `NavigationStack` (iOS 16+) replaces the older `NavigationView`. Use it for proper path-based navigation.
- For iPad, consider a sidebar (`NavigationSplitView`) instead of tab bar for better space utilization.
- The theme system should be the single source of truth for all visual values. No hardcoded colors anywhere in the app.
- Use SF Symbols for icons where possible. For custom icons (ShieldAI logo), use vector PDFs in assets.