> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobile-starter.amisi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Branding Configuration

> Customize your app's icons, splash screens, and visual assets

## Asset Requirements

### App Icon

**Standard Icon (iOS & Android)**

* Size: 1024x1024 px
* Format: PNG
* No transparency
* Square shape (rounded corners applied automatically)

### Adaptive Icon (Android)

**Foreground Image**

* Size: 1024x1024 px
* Format: PNG
* Can have transparency
* Safe zone: Center 66% (outer 17% may be masked)

**Background Color**

* Hex color code (e.g., `#ffffff`)
* Used behind foreground image

### Splash Screen

**Splash Icon**

* Recommended: 200-400 px width
* Format: PNG
* Can have transparency
* Centered on background color

**Background Color**

* Hex color code
* Fills entire screen

## Using the Configurator (Recommended)

The Configurator provides a visual interface for uploading and managing assets:

1. Start the Configurator:

```bash theme={null}
bun run configurator:dev
```

2. Navigate to the **App** section

3. Upload assets:
   * Click **Upload Icon** to upload your app icon
   * Click **Upload Adaptive Icon** for Android foreground image
   * Click **Upload Splash** for splash screen icon

4. Set colors:
   * Adaptive icon background color
   * Splash screen background color

5. Click **Save** to persist changes

6. Click **Apply** to update `app.json` and copy assets

The Configurator automatically:

* Resizes images if needed
* Saves assets to `apps/mobile/assets/images/`
* Updates paths in `amisi.config.json` and `app.json`

## Manual Configuration

### 1. Prepare Your Assets

Create your icon and splash screen assets according to the requirements above.

### 2. Add Assets to Project

Copy your assets to `apps/mobile/assets/images/`:

```
apps/mobile/assets/images/
├── icon.png              # App icon (1024x1024)
├── adaptive-icon.png     # Android foreground (1024x1024)
└── splash-icon.png       # Splash screen icon
```

### 3. Update Configuration

Edit `amisi.config.json`:

```json theme={null}
{
  "branding": {
    "icon": "./assets/images/icon.png",
    "adaptiveIconForeground": "./assets/images/adaptive-icon.png",
    "splash": "./assets/images/splash-icon.png"
  }
}
```

### 4. Update app.json

Edit `apps/mobile/app.json`:

```json theme={null}
{
  "expo": {
    "icon": "./assets/images/icon.png",
    "splash": {
      "image": "./assets/images/splash-icon.png",
      "resizeMode": "contain",
      "backgroundColor": "#ffffff"
    },
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/images/adaptive-icon.png",
        "backgroundColor": "#ffffff"
      }
    }
  }
}
```

## Asset Guidelines

### Icon Design Best Practices

* **Keep it simple**: Icons should be recognizable at small sizes
* **Avoid text**: Text becomes unreadable at small sizes
* **Use solid colors**: Gradients may not render well on all devices
* **Test on devices**: Preview on actual devices before finalizing
* **Consider dark mode**: Ensure icon works on both light and dark backgrounds

### Adaptive Icon Guidelines (Android)

* **Safe zone**: Keep important elements in the center 66%
* **Foreground**: Use transparency for non-rectangular shapes
* **Background**: Use a solid color that complements your foreground
* **Preview shapes**: Test with circle, square, rounded square, and squircle masks

### Splash Screen Guidelines

* **Loading indicator**: Keep splash simple, it's shown briefly
* **Brand consistency**: Match your app's visual identity
* **Resize mode**: Use `contain` to prevent cropping
* **Background color**: Choose a color that matches your brand

## Testing Assets

After updating assets:

1. **Clear cache and rebuild**:

```bash theme={null}
bun run clear
```

2. **Prebuild native projects**:

```bash theme={null}
bun run prebuild
```

3. **Run on device/simulator**:

```bash theme={null}
bun run ios
# or
bun run android
```

4. **Check all scenarios**:
   * App icon on home screen
   * Splash screen on launch
   * Adaptive icon shapes (Android)
   * Dark mode appearance (if applicable)

## Asset Generation Tools

### Recommended Tools

* **Figma**: Design and export at exact sizes
* **Sketch**: Professional design tool with export presets
* **Adobe Illustrator**: Vector graphics for scalable icons
* **Icon generators**: Online tools like [appicon.co](https://appicon.co) or [makeappicon.com](https://makeappicon.com)

### Expo Asset Generation

Expo can generate required sizes from your base assets:

```bash theme={null}
npx expo prebuild --clean
```

This generates platform-specific assets in native projects.

## Platform-Specific Considerations

### iOS

* **App Store**: Requires 1024x1024 icon for submission
* **Rounded corners**: Applied automatically by iOS
* **Launch screen**: Uses splash screen configuration
* **Dark mode**: Consider providing dark mode variants

### Android

* **Adaptive icons**: Required for Android 8.0+
* **Legacy icon**: Fallback for older Android versions
* **Shapes**: Different launchers use different shapes
* **Notification icon**: Consider a separate monochrome icon for notifications

## Common Issues

### Icon Not Updating

Clear app cache and reinstall:

```bash theme={null}
bun run clear
bun run prebuild
```

### Splash Screen Flickers

Ensure `resizeMode` is set to `contain` and background color matches your app's initial screen.

### Adaptive Icon Cropped

Keep important elements within the center 66% safe zone.

### Wrong Colors

Verify hex color codes in `app.json` match your design specifications.

## Next Steps

* [Set Up EAS](/configuration/eas-setup)
* [Configure Firebase](/configuration/firebase-setup)