Skip to main content

Sparki Mobile App UI/UX Specification

Executive Summary

Sparki’s mobile application delivers on-the-go CI/CD management optimized for quick checks, notifications, approvals, and emergency interventions. This specification defines the complete UI/UX system for iOS and Android native apps, emphasizing touch-friendly design, offline capability, and real-time notifications. :::info mobile-philosophy Sparki Mobile Philosophy: “Get what you need in 10 seconds. Approve deployments from anywhere. Know when things break.” Mobile is not a “web view in an app”—it’s a focused, purpose-built experience for developers who need CI/CD status while commuting, in meetings, or away from desk. Focus on: quick glances, one-handed use, push notifications, and critical actions (approvals, rollbacks). :::

Part 1: Design System (Mobile-Optimized)

Touch Target Sizing

All interactive elements must meet platform guidelines:
  • Minimum: 44px × 44px (iOS HIG)
  • Recommended: 48px × 48px (Android Material, easier for large hands)
  • Spacing between targets: minimum 8px
Actual implementations:
Button height:       48px (standard), 52px (prominent)
Tab bar height:      56px (iOS), 64px (Android)
Status badge:        40px × 40px
Avatar/Icon:         44px × 44px
List item:          64px minimum height

Simplified Color Palette (Mobile)

Primary:     #2563EB (Sparki blue)
Accent:      #F97316 (Orange for actions)
Success:     #10B981 (Green)
Error:       #EF4444 (Red)
Warning:     #F59E0B (Orange)

Background:  #FFFFFF (light mode), #111827 (dark mode)
Secondary:   #F3F4F6 (light), #1F2937 (dark)
Text:        #1F2937 (light mode), #F3F4F6 (dark mode)
Divider:     #E5E7EB (light), #374151 (dark)

Typography (Mobile-Optimized)

Title/Screen Name:   18px, 700 weight (easier to read at arm's length)
Subtitle:            16px, 600 weight
Body:                14px, 400 weight (readable on phone)
Small/Caption:       12px, 400 weight (secondary info only)
Monospace (logs):    12px, "IBM Plex Mono" (compact yet readable)
Line Heights:
  • Title: 24px (tighter spacing, fits more on screen)
  • Body: 20px (easy to read on small screens)
  • Small: 16px (compact)

Bottom Sheet Pattern

Mobile-optimized alternative to modals:
┌──────────────────────────────────┐
│  Swipe handle (20px bar)         │ ← User can swipe down to close
│                                  │
│  [Title]                    [×]  │
│                                  │
│  [Content]                       │
│                                  │
│  [Action button]                 │
│                                  │
└──────────────────────────────────┘
Advantages:
  • Easier to close with thumb
  • Smooth animation (swipe dismissal)
  • Content visible beneath (context retained)
  • Natural scrolling within sheet

Part 2: Core Screens & Navigation

Tab Navigation (Primary Structure)

┌──────────────────────────────────┐
│  [Sparki] [Notification badge]   │  ← Status bar
├──────────────────────────────────┤
│  [Screen content]                │
│  [Scrollable if needed]          │
│                                  │
│                                  │
│                                  │
├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │ Bottom tab bar
└──────────────────────────────────┘
5 Primary Tabs:
  1. Home: Dashboard (recent builds, deployments, alerts)
  2. Builds: All builds (filter, search, status)
  3. Deployments: Deployment approvals + history
  4. Monitoring: Quick metrics & health status
  5. Account: Profile, settings, workspaces

Screen 1: Dashboard / Home

Purpose: Quick overview, latest activity, urgent items
┌──────────────────────────────────┐
│ Sparki              [Notification]  │ Status bar
├──────────────────────────────────┤
│ [Workspace Selector ▼]           │
│                                  │
│ ┌─ Quick Stats ─────────────────┐
│ │ Builds:     ✓ 98% | ⏳ 1     │
│ │ Deployments: ✓ 3  | ⚠ 1     │
│ │ Errors:      2     | Warnings: 5 │
│ └──────────────────────────────┘

│ ┌─ Pending Actions ──────────────┐
│ │ 🔴 Deployment approval (1)    │
│ │    → api to prod               │
│ │    Waiting for: Sarah, Mike    │
│ │                                │
│ │ 🔴 Build failure (api/main)   │
│ │    Test timeout after 45s     │
│ │    [View logs]                │
│ └──────────────────────────────┘

│ ┌─ Recent Builds ────────────────┐
│ │ ✓ api/main      5 min ago     │
│ │ ✓ web/main      18 min ago    │
│ │ ✗ worker/dev    42 min ago    │
│ │ ⏳ worker/main   running...    │
│ └──────────────────────────────┘

│ ┌─ Recent Deployments ───────────┐
│ │ ✓ api → prod      6h ago      │
│ │ ✓ web → staging   2h ago      │
│ │ ⚠ worker → staging 30m ago    │
│ └──────────────────────────────┘

├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
REQ-MOBILE-HOME-001: Quick Stats
  • Tap to drill down: “Build success rate” → see builds list filtered to failures
  • Color-coded indicators (green/yellow/red)
  • One-tap access to critical items
REQ-MOBILE-HOME-002: Pending Actions
  • Push notification → tap to jump to pending action
  • Deployment approvals show who needs to approve
  • Build failures show error summary (not full logs, just headline)
REQ-MOBILE-HOME-003: Refresh Mechanism
  • Pull-to-refresh gesture (drag screen down)
  • 1-second delay before refresh completes (feels snappy)
  • Show refresh spinner only if > 1 second

Screen 2: Builds List & Build Details

Builds List:
┌──────────────────────────────────┐
│ Builds              [Filter ⋮]     │
├──────────────────────────────────┤
│ [Project filter ▼] [Sort ▼]      │
│                                  │
│ ┌─ Build ────────────────────────┐
│ │ ✓ api/main                     │
│ │   Commit: abc123 (#234)        │
│ │   5 min ago • 2m 34s           │
│ │                                │
│ │ Triggered by: [User avatar]    │
│ │                                │
│ │ [View] [Cancel] [Retry]        │
│ └────────────────────────────────┘

│ ┌─ Build ────────────────────────┐
│ │ ✗ web/main                     │
│ │   Commit: def456 (#567)        │
│ │   18 min ago • 1m 45s          │
│ │   Failed at: Lint step         │
│ │                                │
│ │ [View] [View on GitHub]        │
│ └────────────────────────────────┘

│ ┌─ Build ────────────────────────┐
│ │ ⏳ worker/main                  │
│ │   Commit: ghi789 in progress   │
│ │   Building... (45s elapsed)    │
│ │   Estimated: 2m 15s            │
│ │                                │
│ │ [Cancel]                       │
│ └────────────────────────────────┘

│ [Load more]                       │
│                                  │
├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
Build Details:
┌──────────────────────────────────┐
│ ← api/main #1234          [···]  │
├──────────────────────────────────┤
│ Status: ✓ PASSED                 │
│ Duration: 2m 34s                 │
│ When: 5 min ago                  │
│                                  │
│ Triggered by:                    │
│ [Avatar] Sarah Chen              │
│ Commit: abc123                   │
│ PR: #234 "Add auth endpoint"     │
│                                  │
│ ┌─ Job Timeline ─────────────────┐
│ │ ✓ Checkout (30s)               │
│ │ ✓ Build (2m 10s)               │
│ │   [Expand]                     │
│ │ ✓ Test (22s)                   │
│ │   [Expand]                     │
│ │ ✓ Lint (12s)                   │
│ │   ⚠ 2 warnings                │
│ │   [View]                       │
│ │ ✓ Publish (10s)                │
│ │ ✓ Deploy Staging (20s)         │
│ └────────────────────────────────┘

│ [Retry] [Deploy to Prod] [Logs]  │
│                                  │
├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
Logs View (when expanded):
┌──────────────────────────────────┐
│ ← Build (2m 10s)                 │
├──────────────────────────────────┤
│ $ go build ./cmd/api              │
│ go: downloading module...         │
│ ... (many lines of output)        │
│ ✓ Build complete                 │
│                                  │
│ [↓ Load more] [Download logs]    │
│                                  │
├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
REQ-MOBILE-BUILDS-001: Optimized List Display
  • Show only: Status, project/branch, time, commit
  • Expand for details (not full modal, just expand item in list)
  • Swipe left to quick actions (View, Retry, Cancel)
  • Long-press for context menu (Copy commit hash, view on GitHub, etc.)
REQ-MOBILE-BUILDS-002: Log Streaming (Mobile-Optimized)
  • Show last 50 lines initially (not first 50, last 50—most relevant)
  • Tap “Load more” to see earlier logs
  • Syntax highlighting for error patterns (make errors stand out)
  • Copy button for each log line (long-press to select multiple)

Screen 3: Deployments & Approval Workflow

Deployments List:
┌──────────────────────────────────┐
│ Deployments         [Filter ⋮]    │
├──────────────────────────────────┤
│ ┌─ Pending Approval ──────────────┐
│ │ 🔴 api → prod                  │
│ │    Waiting for 2 approvals      │
│ │                                │
│ │ Version: v1.2.4                │
│ │ From: staging (1.2.3)          │
│ │                                │
│ │ [Approve] [Request Changes]    │
│ └────────────────────────────────┘

│ ┌─ In Progress ───────────────────┐
│ │ ⏳ worker → staging             │
│ │    Deployed 2 min ago          │
│ │    Health: ⏳ checking...      │
│ │    Rollback available          │
│ │                                │
│ │ [View logs] [Rollback]         │
│ └────────────────────────────────┘

│ ┌─ Recent Deployments ────────────┐
│ │ ✓ web → prod (6h ago)          │
│ │ ✓ api → prod (1d ago)          │
│ │ ✗ rbk worker → staging (2d ago)│
│ └────────────────────────────────┘

├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
Approval Sheet:
┌──────────────────────────────────┐
│     Swipe handle                 │ ← Pull down to close
├──────────────────────────────────┤
│ Approve Deployment               │
│                                  │
│ Project: api                     │
│ Version: v1.2.4 → prod          │
│                                  │
│ ┌─ Changes ──────────────────────┐
│ │ Commits: 3                     │
│ │ Files changed: 12              │
│ │                                │
│ │ [View details on GitHub]       │
│ │                                │
│ │ [View recent builds]           │
│ └────────────────────────────────┘

│ ┌─ Who's approved ───────────────┐
│ │ ✓ Sarah Chen                   │
│ │ ⏳ Mike Rodriguez               │
│ │ ⏳ Jordan Lee                   │
│ └────────────────────────────────┘

│ Add comment (optional):          │
│ ┌────────────────────────────────┐
│ │ Looks good                     │
│ └────────────────────────────────┘

│ [Cancel]  [Request Changes]      │

│ ┌─────────────────────────────────┐
│ │     [APPROVE]                   │
│ └─────────────────────────────────┘

└──────────────────────────────────┘
REQ-MOBILE-DEPLOY-001: One-Tap Approval
  • Push notification → tap → bottom sheet slides up
  • Minimal friction: See key info + approve button
  • One tap to approve (no confirmation dialog)
  • Swipe down to dismiss (if accidental)
REQ-MOBILE-DEPLOY-002: Context Before Approving
  • Show commits since last version
  • Link to GitHub PR/commits
  • Show who’s already approved
  • Build history (did recent builds pass?)
REQ-MOBILE-DEPLOY-003: Quick Rollback
  • In deployment details, prominent rollback button
  • Confirm action: “Rollback to v1.2.2?” with version
  • One-tap confirm (not “are you sure?” fatigue)
  • Show rollback progress in real-time

Screen 4: Monitoring & Alerts

Quick Metrics Dashboard:
┌──────────────────────────────────┐
│ Monitoring            [Refresh]   │
├──────────────────────────────────┤
│ [Workspace ▼]                    │
│                                  │
│ ┌─ System Health ────────────────┐
│ │ ✓ API Status: Healthy          │
│ │   Uptime: 99.98%               │
│ │   Error rate: 0.02%            │
│ │                                │
│ │ ✓ Database: Healthy            │
│ │   Connections: 42/100          │
│ │   Latency p95: 120ms           │
│ │                                │
│ │ ✓ Cache: Healthy               │
│ │   Hit rate: 94.2%              │
│ │   Memory: 3.2GB/4GB            │
│ └────────────────────────────────┘

│ ┌─ Active Alerts ────────────────┐
│ │ ⚠ High error rate detected     │
│ │   prod/api: 2.5% errors        │
│ │   Started: 5 min ago           │
│ │   Affected: 42 users           │
│ │                                │
│ │   [View logs] [Incident]       │
│ │                                │
│ │ ⚠ Slow deployment in progress │
│ │   web → prod                   │
│ │   Health check: 8min/10min     │
│ │                                │
│ │   [Auto-rollback in 2min] [Rollback now]│
│ └────────────────────────────────┘

│ ┌─ Metrics (Last 24h) ───────────┐
│ │ [Graph: Error rate trend]      │
│ │ [Graph: Response time]         │
│ │ [Graph: Deployment frequency]  │
│ └────────────────────────────────┘

├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘
REQ-MOBILE-MONITORING-001: Critical Alerts Only
  • No alert fatigue (filter to high-severity only)
  • Color-coded: Red (critical), Orange (warning), Green (healthy)
  • Direct action buttons: View logs, Rollback, Incident investigation
REQ-MOBILE-MONITORING-002: Sparkline Graphs
  • Mini charts showing last 24h trend
  • Tap to zoom into time range
  • No detailed time series (phone screen is small)
  • Color: Green (good) → Orange (concerning) → Red (critical)

Screen 5: Account & Settings

Account Tab:
┌──────────────────────────────────┐
│ Account                      [Edit]│
├──────────────────────────────────┤
│ ┌─ Profile ──────────────────────┐
│ │ [Avatar XXL]                   │
│ │ Sarah Chen                      │
│ │ sarah@sparki.dev               │
│ │ Pro tier • Team: Sparki Inc     │
│ └────────────────────────────────┘

│ ┌─ Workspaces ──────────────────┐
│ │ Sparki Inc (current)           │
│ │   Role: Admin                  │
│ │   [Switch]                     │
│ │                                │
│ │ Personal workspace             │
│ │   Role: Owner                  │
│ │   [Switch]                     │
│ │                                │
│ │ [+ Create workspace]           │
│ └────────────────────────────────┘

│ ┌─ Preferences ──────────────────┐
│ │ Notifications                  │
│ │   [Toggle: ON]  [Settings...]  │
│ │                                │
│ │ Dark mode                      │
│ │   [Toggle: System preference]  │
│ │                                │
│ │ Build notifications            │
│ │   [Toggle: Failures only]      │
│ │                                │
│ │ [Manage notification topics]   │
│ └────────────────────────────────┘

│ ┌─ Security ─────────────────────┐
│ │ API Keys                       │
│ │   [Manage]                     │
│ │                                │
│ │ Two-factor authentication      │
│ │   [Toggle: ON]                 │
│ │                                │
│ │ Session timeout                │
│ │   [5 min] [Customize]          │
│ └────────────────────────────────┘

│ [Sign out] [Delete account]       │
│                                  │
├──────────────────────────────────┤
│ 🏠 │ 🔨 │ 🚀 │ ⚙️ │ 👤 │
└──────────────────────────────────┘

Part 3: Push Notifications

REQ-MOBILE-NOTIFY-001: Notification Types & Urgency

High Urgency (Immediate notification, sound + badge):
  • Deployment approval requested (you specifically need to act)
  • Production deployment failed (rollback initiated automatically)
  • Build failure blocking merge (critical path)
  • Incident alert (error rate spike, SLA violation)
Medium Urgency (Notification, no sound):
  • Build completed (if you opted in for all builds)
  • Deployment started/completed (if you’re watching)
  • Test warning (flaky tests detected)
Low Urgency (Badge only, in-app notification):
  • New team member added
  • Workspace invite
  • API usage warning (approaching quota)
Implementation:
{
    "alert": {
        "title": "Deployment Approval Needed",
        "body": "api v1.2.4 → prod. Waiting for 1 approval.",
        "subtitle": "Sarah Chen needs your approval"
    },
    "badge": 1,
    "sound": "default",
    "priority": "high",
    "custom_data": {
        "deployment_id": "deploy_123",
        "action_type": "approval_requested",
        "deep_link": "sparki://deployments/deploy_123"
    }
}

REQ-MOBILE-NOTIFY-002: Notification Actions

Direct replies from notification:
  • Approve deployment (without opening app)
  • Add comment (quick text input from notification)
  • View logs (tap → jump to build details)
Grouped notifications:
  • Multiple build failures → “3 builds failed. Tap to view.”
  • Multiple approvals needed → “You have 2 approvals pending”

Part 4: Offline Support & Resilience

REQ-MOBILE-OFFLINE-001: Offline Capabilities

Read-Only Offline:
  • View cached builds (from last hour)
  • View cached deployments
  • View cached alerts
  • Show “last updated: 2 hours ago” indicator
Limited Online (Slow connection):
  • Retry failed requests (exponential backoff)
  • Show data staleness indicator
  • Allow approvals (queue approval, send when online)
  • Show “Reconnecting…” banner

REQ-MOBILE-OFFLINE-002: Progressive Enhancement

  • Core feature: View recent builds (works offline)
  • Enhanced feature: Real-time updates (requires online)
  • Premium feature: Advanced analytics (requires fresh data)

Part 5: Platform-Specific Patterns

iOS-Specific

Navigation:
  • Back button in top-left (system standard)
  • Bottom tab navigation (iOS convention)
  • Swipe-back gesture for pop navigation
Interactions:
  • 3D touch for quick actions (preview deployment before approving)
  • Haptic feedback: Light (tap), Medium (success), Heavy (error)
  • Activity indicator style (iOS native spinner)
Hardware:
  • Face ID support (biometric login)
  • Home indicator safe area (notch/dynamic island aware)
  • Status bar color changes with screen

Android-Specific

Navigation:
  • Hamburger menu (Material Design convention)
  • Bottom navigation bar with labels
  • Back button (or gesture) for pop
Interactions:
  • Material Design transitions (ripple effects, elevation)
  • Haptic feedback: Light tick (system default)
  • Material spinners and loaders
Hardware:
  • Fingerprint support (biometric login)
  • SafeArea for system gestures
  • Material 3 dynamic theming (match system colors on Android 12+)

Part 6: Performance Targets (Mobile)

REQ-MOBILE-PERFORMANCE-001: Load Times

  • App launch: under 2 seconds (cold start)
  • Tab switch: under 300ms (cached data)
  • Data refresh (builds list): under 1 second
  • Notification tap → screen open: under 500ms
  • Push notification → receipt: under 5 seconds

REQ-MOBILE-PERFORMANCE-002: Bandwidth Optimization

  • Build list: under 50KB per request (gzip)
  • Deployment details: under 30KB
  • Full logs: stream (not load all at once)
  • Images: WebP format, max 100px width thumbnails

REQ-MOBILE-PERFORMANCE-003: Battery & Resource Usage

  • Background refresh: every 15 minutes (not draining battery)
  • WebSocket: disconnect when app backgrounded
  • Reconnect when app foregrounded
  • Limit notifications: No more than 1 per minute per category

Part 7: Technology Stack

iOS Implementation

Framework: Swift + SwiftUI (modern, type-safe) Architecture: MVVM (Model-View-ViewModel) State Management: Combine (Apple’s reactive framework) Networking: URLSession + WebSocket Local Storage: CoreData or Realm Push Notifications: APNs (Apple Push Notification service) Testing: XCTest + Swift Testing

Android Implementation

Framework: Kotlin + Jetpack Compose (modern, type-safe) Architecture: MVVM with clean architecture State Management: StateFlow + SharedFlow Networking: Retrofit + OkHttp + WebSocket Local Storage: Room Database Push Notifications: FCM (Firebase Cloud Messaging) Testing: JUnit + Espresso

Shared Code (Cross-Platform)

Option A: Shared business logic (recommended for Sparki)
Kotlin Multiplatform Mobile (KMM)
├─ Shared: API client, data models, business logic
├─ iOS: SwiftUI UI layer (native)
└─ Android: Compose UI layer (native)
Option B: Single codebase
Flutter or React Native (not recommended for Sparki)
Reason: Performance, platform polish, native features
Recommendation: KMM allows native UI/UX on each platform while sharing API logic

Part 8: Accessibility (Mobile)

REQ-MOBILE-ACCESSIBILITY-001: Screen Reader Support

  • All buttons have descriptive labels (not just icons)
  • Image descriptions for status badges
  • Form fields have associated labels
  • Dynamic text size support (iOS) and text scaling (Android)

REQ-MOBILE-ACCESSIBILITY-002: Haptic Feedback

  • Every action has haptic response (tap feedback)
  • Different haptics for success (pattern) vs error (heavy)
  • Disable-able in accessibility settings

REQ-MOBILE-ACCESSIBILITY-003: High Contrast Mode

  • Support dark mode + light mode
  • 4.5:1 color contrast minimum
  • Option for bold text in settings

Part 9: Security & Biometrics

REQ-MOBILE-SECURITY-001: Biometric Authentication

  • Support Face ID / Touch ID (iOS)
  • Support Fingerprint / Face unlock (Android)
  • Fallback to password if biometric fails
  • Biometric re-prompt every 15 minutes (if inactive)

REQ-MOBILE-SECURITY-002: Data Protection

  • All data encrypted at rest (iOS: Keychain, Android: EncryptedSharedPreferences)
  • API keys stored securely (never in plaintext)
  • Session tokens: 30-minute expiry
  • Kill app session if unlock fails 3 times

REQ-MOBILE-SECURITY-003: Certificate Pinning

  • Pinning certificate to prevent MITM attacks
  • Graceful degradation if certificate updates
  • Monitoring for suspicious traffic

Part 10: Onboarding & Deep Linking

REQ-MOBILE-ONBOARDING-001: First Launch

Screen 1: Welcome
"Build, Test, Deploy Anywhere"
Subtitle: "Stay on top of your CI/CD"
[Get Started]

Screen 2: Sign in
[Email input]
[Password input]
[Sign in] [Create account]

Screen 3: Workspaces
"Choose a workspace"
[Workspace 1] [Workspace 2]
[Or create new]

Screen 4: Permissions
"Sparki needs:"
✓ Notification permissions
✓ Biometric permission
[Continue]

Screen 5: Dashboard
Now showing dashboard with recent builds

REQ-MOBILE-ONBOARDING-002: Deep Linking

Supported deep links:
sparki://deployments/{deployment_id}
sparki://builds/{build_id}
sparki://approvals
sparki://projects/{project_id}
sparki://settings
Implementation:
  • Deep link from push notification
  • Deep link from email campaign
  • Deep link from web (App Clips on iOS)
  • Falls back to manual navigation if app doesn’t support

Conclusion

Sparki’s mobile app provides fast, focused access to CI/CD management with emphasis on approvals, alerts, and quick checks. Every design decision prioritizes:
  • Speed: Launch in 2 seconds, approve in 3 taps
  • Accessibility: Touch-friendly, screen reader support
  • Reliability: Works offline, graceful degradation online
  • Native feel: Platform-specific patterns (iOS/Android)
  • Security: Biometric auth, encrypted storage

Document Statistics:
MetricValue
Screens Specified5 primary (Dashboard, Builds, Deployments, Monitoring, Account)
Platform-Specific Sections2 (iOS, Android)
Interaction Patterns8+ (Notifications, Approval, Deep linking, Offline, etc.)
Touch Target Optimization44-48px minimum
Accessibility Features5+ (Screen reader, Haptics, Contrast, etc.)
Push Notification Types3 urgency levels
Technology Stack DetailsComplete (Swift, Kotlin, KMM recommended)
Total Words~8,000
StatusCOMPLETE

Document History:
VersionDateAuthorChanges
1.02025-12-03Sparki Mobile DesignComplete mobile UI/UX specification