app-icon

App Icon Generation Workflow

Overview

Generate professional app icons using AI and configure them for both iOS (with iOS 26 Liquid Glass support) and Android platforms in Expo apps.

Step 0: Verify SnapAI Setup (CRITICAL - DO THIS FIRST)

SnapAI is a free, open-source CLI built by the Code with Beto team. It calls the selected image provider directly using the user's API key. A key can be stored locally at ~/.snapai/config.json or supplied through an environment variable. SnapAI ships no telemetry and has no backend server.

Before attempting to generate icons, check if SnapAI is configured:

1. Check if SnapAI is configured:

npx snapai config --show

2. If the config check fails or shows no API key:

   • SnapAI requires an OpenAI API key to generate icons
   • Ask the user: "SnapAI requires an OpenAI API key. Do you have one, or would you like me to help you set it up?"

3. If the user has an API key:

   • Never ask the user to paste the secret into chat, source code, or a command you will run
   • Ask them to configure it locally in their own terminal with:

   npx snapai config --openai-api-key "<their-api-key>"
   • Alternatively, they can set SNAPAI_API_KEY or OPENAI_API_KEY in their shell or secret manager
   • After the user confirms setup is complete, verify it without printing the secret:

   npx snapai config --show

4. If the user needs to get an API key:

   • Direct them to: https://platform.openai.com/api-keys
   • Explain: "You'll need to:
     1. Create an OpenAI account if you don't have one
     2. Navigate to API keys section
     3. Click 'Create new secret key'
     4. Copy the key (starts with 'sk-')
     5. Configure it locally without sharing it in chat"

Important Notes:

• SnapAI is open source. API requests go directly to the selected provider; the tool has no intermediary backend.
• The tool itself is free; provider API usage is billed according to the user's provider account.
• Do NOT proceed with icon generation if SnapAI is not configured
• Do not expose credentials in chat, command output, logs, or committed files

Step 1: Understand the App Context

• Read the app.json to understand the app name and current icon configuration
• Ask the user what the app is about if not clear from context
• Identify the app's theme, purpose, and target aesthetic

Step 2: Get Style Preferences

Ask the user what style they'd like for the icon. Available styles:

• minimalism - Clean, Apple-inspired minimalism (2-3 colors max)
• glassy - Premium glass aesthetic with semi-transparent elements
• gradient - Vibrant gradients, Instagram-inspired
• neon - Cyberpunk, futuristic with glowing effects
• material - Google Material Design
• ios-classic - Traditional iOS with subtle gradients
• pixel - Retro 8-bit/16-bit game art style
• geometric - Bold, angular compositions

Or let the user provide a custom style description.

Step 3: Generate Icon with SnapAI

Pre-flight check: Verify SnapAI is configured before running (see Step 0)

Generate a 1024x1024 icon with transparent background (critical for both platforms):

npx snapai icon --prompt "YOUR_PROMPT_HERE" --background transparent --output-format png --style STYLE_NAME

Important flags:

• --background transparent - REQUIRED for iOS 26 and Android adaptive icons
• --output-format png - Ensures PNG format
• --style - Optional, enhances the visual style
• --quality high - Optional, for final production icons

The icon will be saved to ./assets/icon-[timestamp].png

Step 4: Create iOS 26 .icon Folder Structure

Create the new iOS 26 Liquid Glass icon format:

1. Create the folder structure:

mkdir -p assets/app-icon.icon/Assets

2. Copy the generated PNG:

cp assets/icon-[timestamp].png assets/app-icon.icon/Assets/icon.png

3. Create assets/app-icon.icon/icon.json with this basic configuration:

{
  "fill": "automatic",
  "groups": [
    {
      "layers": [
        {
          "glass": false,
          "image-name": "icon.png",
          "name": "icon"
        }
      ],
      "shadow": {
        "kind": "neutral",
        "opacity": 0.5
      },
      "translucency": {
        "enabled": true,
        "value": 0.5
      }
    }
  ],
  "supported-platforms": {
    "circles": ["watchOS"],
    "squares": "shared"
  }
}

Step 4.5: Create Android-Optimized Adaptive Icon

Android adaptive icons have a smaller safe area (~66% of the canvas) compared to iOS. The main icon generated by SnapAI is optimized for iOS safe areas, which means it may appear too large and get clipped on Android devices with circular or squircle masks.

To ensure your icon displays correctly on all Android device shapes (circles, squircles, rounded squares), create a scaled-down version:

Using ImageMagick (recommended):

# Scale the icon to 66% and center it on a 1024x1024 transparent canvas
magick assets/icon-[timestamp].png \
  -resize 66% \
  -gravity center \
  -background transparent \
  -extent 1024x1024 \
  assets/android-icon.png

Alternative - Using sips + ImageMagick (macOS):

# Step 1: Resize to 66% (676x676)
sips -Z 676 assets/icon-[timestamp].png --out /tmp/icon-resized.png
 
# Step 2: Create the final centered image
magick -size 1024x1024 xc:transparent /tmp/icon-resized.png \
  -gravity center -composite assets/android-icon.png

Note: If ImageMagick is not installed, install it with:

brew install imagemagick

Step 5: Update app.json

Update the app.json to configure icons for both platforms:

For iOS:

{
  "expo": {
    "ios": {
      "icon": "./assets/app-icon.icon"
    }
  }
}

For Android:

Use the Android-optimized icon created in Step 4.5:

Option 1: Simple (with solid background color)

{
  "expo": {
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/android-icon.png",
        "backgroundColor": "#ffffff"
      }
    }
  }
}

Option 2: Comprehensive (recommended) Since the icon has a transparent background, you can use it for all three Android adaptive icon fields:

{
  "expo": {
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/android-icon.png",
        "backgroundImage": "./assets/android-icon.png",
        "monochromeImage": "./assets/android-icon.png"
      }
    }
  }
}

Benefits of Option 2:

• foregroundImage - Main icon displayed
• backgroundImage - Provides layered depth effect on Android 8.0+
• monochromeImage - Used for themed icons on Android 13+ (automatically recolored by system)

Note:

• For Option 1, ask the user for their preferred backgroundColor, or use white (#ffffff) as default
• For Option 2, the same transparent PNG works perfectly for all three fields
• Option 2 provides better integration with Android's Material You theming

Step 6: Verify and Test

1. Verify the folder structure exists:

ls -la assets/app-icon.icon/

2. Verify app.json is valid JSON:

cat app.json | jq .

3. Inform the user to test the app with:

npx expo prebuild --clean
npx expo run:ios
npx expo run:android

Important Notes

• Transparent background is critical - The icon must have a transparent background for both iOS Liquid Glass effect and Android adaptive icons
• iOS 26 .icon format - The .icon folder enables Liquid Glass effects on iOS 26+
• Dual-asset workflow - This skill generates two icon assets:
  • icon-[timestamp].png - Main icon optimized for iOS safe areas (used in .icon folder)
  • android-icon.png - Scaled to 66% and centered for Android adaptive icon safe areas
• Why two assets? - iOS and Android have different safe zones. iOS allows content closer to edges (~80-85%), while Android adaptive icons only guarantee ~66% of the center is visible due to aggressive masking (circles, squircles, etc.)
• Android adaptive icon flexibility - The android-icon.png can be used for foregroundImage, backgroundImage, AND monochromeImage fields
• Material You support - Using monochromeImage enables Android 13+ themed icons that adapt to user's color scheme
• File naming - The .icon folder name can be customized (e.g., app-icon.icon, myapp.icon)

Troubleshooting

SnapAI Configuration Issues

• "No API key found" - Ask the user to run npx snapai config --openai-api-key "<key>" locally, or set SNAPAI_API_KEY / OPENAI_API_KEY
• "Invalid API key" - Ask the user to verify or rotate the key in their OpenAI account without sharing it in chat
• Authentication errors - Check if the API key has been revoked or has insufficient credits at platform.openai.com
• Command not found - Ensure you're using npx snapai (not just snapai)

Icon Display Issues

• If the icon doesn't appear, verify the path in app.json matches the actual folder location
• Ensure the PNG inside the .icon folder is exactly 1024x1024
• For Android, make sure all image paths (foregroundImage, backgroundImage, monochromeImage) are correct and point to existing files
• Run npx expo prebuild --clean to regenerate native projects after icon changes

ImageMagick Issues (for Android icon)

• "convert: command not found" - Install ImageMagick with brew install imagemagick
• Permission denied - Ensure you have write access to the assets folder
• Icon still appears clipped on Android - Try reducing the resize percentage from 66% to 60% for more aggressive safe area compliance