Skip to content

IOS_ICON_GUIDE.md

Latest commit

 

History

History
86 lines (59 loc) · 2.41 KB

IOS_ICON_GUIDE.md

File metadata and controls

86 lines (59 loc) · 2.41 KB

📱 iOS App Icon Theme Switching Guide

⚠️ Important iOS Limitation

iOS does NOT support dynamic theme switching for PWA home screen icons.

How iOS Handles PWA Icons:

  1. During "Add to Home Screen": iOS picks ONE icon based on current theme
  2. After adding: Icon stays the same regardless of theme changes
  3. To update icon: Must remove app and re-add to home screen

This is a limitation of iOS Safari/WebKit, not your app configuration.

🎯 Recommended Solution: Universal Icon

Create one icon that works well in both light and dark themes:

✅ Best Practices for Universal Icons:

  1. Use neutral colors (works in both themes)
  2. Avoid pure white/black backgrounds
  3. Add subtle borders for contrast
  4. Test on both light/dark home screens

🎨 Design Tips:

✅ Good Universal Colors:
- Brand colors (blue, green, purple, etc.)
- Gradients with neutral tones
- Icons with colored backgrounds
- Subtle shadows/borders

❌ Avoid:
- Pure white backgrounds (invisible on light mode)
- Pure black backgrounds (invisible on dark mode) 
- Very light colors without borders
- Text-heavy designs

🔄 Alternative: Keep Theme Icons (Limited)

If you prefer separate theme icons, users need to:

  1. Light Mode: Remove app → Switch to light → Re-add app
  2. Dark Mode: Remove app → Switch to dark → Re-add app

Note: Most users won't do this, so universal icon is better.

🧪 Testing Your Icon

  1. Light Mode Test:

    • Switch iOS to light mode
    • Add app to home screen
    • Check visibility/contrast

  2. Dark Mode Test:

    • Switch iOS to dark mode
    • Add app to home screen
    • Check visibility/contrast

  3. Universal Icon Test:

    • Create one icon
    • Test in both themes
    • Ensure good visibility in both

📱 Current Configuration

Updated to use universal icon:

  • apple-touch-icon.png - Single icon for all themes
  • Removed theme-specific variants to avoid confusion

🎯 Icon Requirements Reminder

  • Size: 180x180 pixels
  • Format: PNG
  • Background: Opaque (iOS adds rounded corners)
  • Safe area: Keep content away from edges
  • Visibility: Must work on both light/dark home screens

💡 Pro Tip

Popular apps like Instagram, Twitter, and WhatsApp use universal icons that work well in both themes. This is the industry standard approach for PWAs on iOS.