# App icon and splash screen

Two roles give an app its icon and the screen that the system shows while the app starts:

| Part | Role | Module | What it brings |
| --- | --- | --- | --- |
| The icon | App icon | [`launcher_icons`](https://doc.saymyframe.com/modules/launcher-icons.md) | An opaque icon on iOS, and an adaptive icon with a themed variant on Android, in place of the logo of Flutter |
| The screen | Splash screen | [`native_splash`](https://doc.saymyframe.com/modules/native-splash.md) | A screen for the light and for the dark mode of the device, in place of the white screen of `flutter create` |

```bash
smf create my_app -m launcher_icons,native_splash
```

A run in a terminal asks for each. A run with `--no-input`, or a `-m` without these modules, keeps the logo of Flutter and a white launch screen.

The tools run once the app has its packages. A run in a terminal asks first, and Enter runs them. A tool that fails costs a warning and the command for later, and you still get the app. The tools are only dev dependencies, so no code of the app imports them.

## The images

The sources are in `assets/branding/`, and the app does not bundle them:

| File | Size | What it is |
| --- | --- | --- |
| `icon.png` | 1024 by 1024, opaque | The icon on iOS and on older versions of Android. The App Store refuses an icon with alpha. |
| `icon_foreground.png` | 1024 by 1024, on a transparent background | The adaptive icon of Android, and through its alpha the themed icon. Launchers cut it to a shape of their own and always keep a circle around its centre, as wide as 90% of the image. |
| `splash_light.png` | 1152 by 1152, on a transparent background | The screen in the light mode of the device |
| `splash_dark.png` | 1152 by 1152, on a transparent background | The screen in the dark mode of the device. Android 12 and later cut both images to a circle of two thirds of their width. |

As generated, they show the mark of Say My Frame: the icon in cream on green, the screen in green on cream in the light mode and in cream on green in the dark mode. Replace them with your own before you release the app. [TRADEMARKS.md](https://github.com/saymyframe/smf_flutter_cli/blob/main/TRADEMARKS.md) says what holds for the mark.

## Replace them

1. Put your images in place of those in `assets/branding/`, with the same names.
2. Change the colours if they do not suit your images: `adaptive_icon_background` in `flutter_launcher_icons.yaml` is the colour behind the icon on Android, and `color` and `color_dark` in `flutter_native_splash.yaml`, with the same two under `android_12`, are the colours behind the screen.
3. Run the commands of the modules:

   ```bash
   dart tool/update_app_icon.dart
   dart run flutter_native_splash:create
   ```

4. Commit what changed under `android/` and `ios/`.

Use the script for the icon rather than `dart run flutter_launcher_icons`. The tool writes the name of the icon into a build setting of the Xcode project that takes `YES` or `NO`, and the script repairs that setting.

## One icon for all flavors

All [flavors](https://doc.saymyframe.com/guides/flavors.md) share the icon and the screen. A file for a flavor does not change that: `flutter_launcher_icons-<flavor>.yaml` turns `flutter_launcher_icons.yaml` off and does not switch the icon of a flavor on iOS, and on iOS the app keeps showing the screen of `flutter_native_splash.yaml` with a `flutter_native_splash-<flavor>.yaml` too. So one icon for each flavor needs more than those files.

## A module of your own

A module can provide either role, or both. See [Provide a role](https://doc.saymyframe.com/extending/role-provider.md#app-icon-and-splash-screen).