Skip to content

title: Onboarding Flow description: First-run user onboarding experience last_updated: 2025-12-24 status: active audience: users category: user-guide tags:

  • onboarding
  • first-run
  • ux

Onboarding Flow¶

StormTunnel features a comprehensive 4-step onboarding process that guides new users through initial setup, security configuration, SSH key import, and privacy policy acceptance.

🎯 Overview¶

The onboarding system provides a structured introduction to StormTunnel, ensuring users understand key features and make informed decisions about security and privacy settings.

Design Principles¶

  • Progressive Disclosure: Information revealed in logical steps
  • User Control: Users can skip non-essential steps
  • Accessibility: Full support for screen readers and keyboard navigation
  • Reduced Motion: Respects user accessibility preferences
  • Visual Consistency: Cohesive design throughout the flow

📋 Onboarding Steps¶

Step 1: Welcome Screen¶

Purpose: Introduction to StormTunnel and its capabilities

Content¶

  • App Introduction: Brief overview of StormTunnel's purpose
  • Key Features: Highlight of main functionality
    • SSH tunnel management
    • AWS Session Manager integration
    • Menu bar convenience
    • Security-focused design
  • Getting Started: Clear call-to-action to begin setup

Visual Elements¶

  • App Icon: Large StormTunnel icon for brand recognition
  • Welcome Illustration: Visual representation of tunnel management
  • Progress Indicator: Shows "Step 1 of 4"
  • Navigation: "Continue" button to proceed to next step

Purpose: Educate users about security implications and obtain consent

Security Information¶

  • Local Storage: Explanation of how SSH keys and tunnels are stored
  • Keychain Integration: Description of secure credential storage
  • Network Access: Information about required network permissions
  • Privacy Commitment: Clear statement about data handling practices
  • Security Features: Toggle for enhanced security settings
    • Secure Memory: Enable memory protection for sensitive data
    • Key Validation: Automatic SSH key security checking
    • Audit Logging: Security event logging for troubleshooting
  • Data Collection: Clear options for what data to collect
  • User Agreement: Explicit consent for security measures

Visual Design¶

  • Security Icons: Lock and shield icons for trust building
  • Progressive Disclosure: Detailed information available on demand
  • Clear Language: Non-technical explanations of security concepts

Step 3: SSH Key Auto-Import¶

Purpose: Automatically discover and import existing SSH keys

Key Discovery Process¶

  • Standard Locations: Scans common SSH key directories
    • ~/.ssh/ (user SSH directory)
    • ~/.ssh/id_rsa, ~/.ssh/id_ed25519 (default key names)
    • Custom paths from SSH configuration
  • Key Types: Supports multiple SSH key formats
    • RSA (traditional)
    • ECDSA (elliptic curve)
    • ED25519 (modern, recommended)
  • Security Analysis: Evaluates key strength and recommendations

Import Interface¶

  • Discovered Keys: List of found keys with metadata
    • Key Type: Algorithm and bit strength
    • File Path: Location of key file
    • Last Modified: Timestamp for relevance
    • Security Status: Visual indicator of key quality

Import Options¶

  • Select All: Quick selection of all discovered keys
  • Individual Selection: Granular control over key import
  • Skip Option: Users can skip if they prefer manual setup
  • Security Validation: Optional key security checking during import

Progress Feedback¶

  • Import Progress: Real-time feedback during key processing
  • Validation Status: Security analysis progress
  • Error Handling: Clear error messages for import failures
  • Success Confirmation: Summary of successfully imported keys

Step 4: Privacy Policy¶

Purpose: Present privacy policy and obtain final consent

Privacy Information¶

  • Data Collection: Clear explanation of what data is collected
    • Local Data Only: Emphasis on local-only storage
    • No Telemetry: Commitment to no data transmission
    • Analytics Option: Optional crash reporting and analytics
  • Data Usage: How collected data is used
    • Feature Improvement: Analytics for app enhancement
    • Bug Fixing: Crash reports for stability
    • Security: Security event logging for protection
  • Privacy Settings: Configurable privacy preferences
    • Crash Reporting: Toggle for automatic crash reports
    • Usage Analytics: Optional anonymous usage statistics
    • Security Logging: Control over security event storage
  • Data Retention: Information about how long data is kept
  • Export Rights: User rights to export their data

Final Actions¶

  • Accept & Continue: Complete onboarding with selected settings
  • Customize Settings: Option to modify privacy preferences
  • Get Started: Launch into main application

🎨 User Experience¶

Keyboard Navigation¶

  • Tab Navigation: Move between interactive elements
  • Arrow Keys: Navigate within lists and options
  • Space/Return: Activate buttons and toggle switches
  • Escape: Go back to previous step (when available)

Focus Management¶

  • Focus Rings: Clear visual indication of focused element
  • Focus Trapping: Logical tab order within each step
  • Auto-focus: Automatic focus on primary action buttons
  • Screen Reader: Proper announcements for state changes

Visual Design¶

Progress Indication¶

  • Step Counter: "Step X of 4" in header
  • Progress Bar: Visual progress through onboarding flow
  • Breadcrumbs: Optional breadcrumb navigation
  • Step Titles: Clear titles for each onboarding step

Animation System¶

  • Reduced Motion: Simple fade transitions for accessibility
  • Standard Motion: Slide transitions with opacity changes
  • Page Transitions: Asymmetric insertion/removal animations
  • Micro-interactions: Subtle feedback for user actions

Responsive Layout¶

  • Window Sizing: Adapts to different screen sizes
  • Content Scaling: Respects system font size settings
  • Dark Mode: Full support for system appearance
  • High Contrast: Respects accessibility contrast settings

🔒 Security Considerations¶

Data Protection¶

  • Local Processing: All onboarding operations happen locally
  • No Network Calls: No data transmitted during onboarding
  • Secure Storage: Imported keys stored using macOS Keychain
  • Permission Respect: All system permissions properly requested

Privacy by Design¶

  • Minimal Data Collection: Only essential information collected
  • Explicit Consent: Clear opt-in for all data collection
  • User Control: Granular control over privacy settings
  • Transparent Policies: Easy-to-understand privacy explanations

Key Security¶

  • Validation: SSH keys validated for security issues
  • Secure Import: Keys processed with security best practices
  • Permission Handling: Proper file permissions for SSH directories
  • Error Sanitization: Error messages sanitized to prevent information leakage

♿ Accessibility Features¶

Screen Reader Support¶

  • Semantic Labels: All UI elements properly labeled
  • Dynamic Announcements: State changes announced
  • Context Information: Progress and navigation status
  • Error Messages: Clear error announcements with recovery options

Keyboard Navigation¶

  • Full Keyboard Access: All features accessible via keyboard
  • Logical Tab Order: Intuitive navigation sequence
  • Focus Indication: Clear visual focus indicators
  • Shortcut Keys: Standard macOS keyboard shortcuts

Visual Accessibility¶

  • High Contrast: Support for system contrast settings
  • Reduced Motion: Alternative animations for motion sensitivity
  • Dynamic Type: Respects system font size preferences
  • Color Blindness: Information not conveyed through color alone

🔄 Onboarding Completion¶

Completion Criteria¶

  • All Steps Visited: User has navigated through all steps
  • Privacy Consent: Privacy policy accepted
  • Security Settings: Security preferences configured
  • Key Import: SSH keys imported (or explicitly skipped)

Post-Onboarding Setup¶

  • Settings Migration: Onboarding preferences transferred to main settings
  • First Launch: Main application launched with configured preferences
  • Tutorial Mode: Optional tutorial hints available in main app
  • Support Resources: Easy access to help and documentation

Skip and Resume¶

  • Partial Completion: Users can skip non-essential steps
  • Resume Capability: Onboarding can be resumed later
  • Settings Access: All onboarding settings available in main settings
  • No Forced Steps: Users maintain control over their setup process

Last Updated: December 20, 2025