Kordant/tasks/kordant-unified-restructure/28-ios-app-foundation.md

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

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

objective:

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

deliverables:

• iOS/Kordant/KordantApp.swift — App entry point:
  • @main app struct with WindowGroup
  • Initializes dependency container (if using DI)
  • Sets up appearance (tint color, navigation bar style)
• iOS/Kordant/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/Kordant/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/Kordant/Theme/ — Shared theme system:
  • KordantTheme.swift — Theme protocol/struct with colors, fonts, spacing
  • Color+Kordant.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+Kordant.swift — Typography scale matching web app
  • ThemeManager.swift — Observable object managing light/dark/system mode
• iOS/Kordant/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/Kordant/ exists and has a valid Xcode project or Package.swift.
2. Create KordantApp.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 (kordant://dashboard, kordant://alert/123)
5. Create theme system:
   • Define all colors as static properties on Color extension
   • Use UIColor dynamic colors for light/dark variants:

     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 Kordant 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 Kordant 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 kordant:// 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 kordant://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 (Kordant logo), use vector PDFs in assets.