---
name: maui-app-icons-splash
description: >
  .NET MAUI app icon configuration, splash screen setup, SVG to PNG conversion
  at build time, composed/adaptive icons, and platform-specific icon and splash
  screen requirements for Android, iOS, Mac Catalyst, and Windows.
  USE FOR: "app icon", "splash screen", "MauiIcon", "MauiSplashScreen", "adaptive icon",
  "change app icon", "launch screen", "SVG icon", "foreground tint", "icon resize".
  DO NOT USE FOR: in-app images or image loading (use maui-performance),
  theming or colors (use maui-theming), or custom drawing (use maui-graphics-drawing).
---

# .NET MAUI App Icons & Splash Screens

## Common Pitfalls

### ❌ Android adaptive icon clipping

Android adaptive icons crop to a circular or squircle safe zone. If the foreground fills the canvas, it **will** be clipped.

```xml
<!-- ❌ Single-layer icon — foreground fills entire canvas, gets clipped -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          Color="#512BD4" />

<!-- ✅ Composed icon with scaled foreground — stays in safe zone -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          ForegroundFile="Resources\AppIcon\appiconfg.svg"
          ForegroundScale="0.65"
          Color="#512BD4" />
```

### ❌ Transparent splash screen Color

Some platforms ignore alpha in the splash `Color` and show **black** instead.

```xml
<!-- ❌ Transparent color — may render as black on some platforms -->
<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#00FFFFFF" />

<!-- ✅ Opaque color -->
<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#512BD4" />
```

### ❌ Confusing Color vs TintColor

- **`Color`** = background fill behind the icon/splash.
- **`TintColor`** = recolors the foreground image itself.

Setting only `TintColor` without visible foreground paths results in a blank icon.

### ⚠️ SVG rendering issues at build time

Complex SVGs with gradients, filters, or masks may not rasterize correctly via the `Microsoft.Maui.Resizetizer` MSBuild task.

```xml
<!-- Workaround: supply a pre-made PNG and skip resizing -->
<MauiIcon Include="Resources\AppIcon\appicon.png"
          Resize="false" />
```

### ⚠️ BaseSize mismatch

If your SVG `viewBox` doesn't match the desired logical size, set `BaseSize` explicitly — otherwise the output dimensions may be wrong.

```xml
<!-- SVG viewBox is 100x100 but you want 456x456 logical output -->
<MauiIcon Include="Resources\AppIcon\appicon.svg"
          BaseSize="456,456"
          Color="#512BD4" />
```

## Best Practices

1. **Use SVG whenever possible** — one file, infinite scaling, smaller repo.
2. **Set `BaseSize` explicitly** when the SVG viewBox doesn't match the desired logical size.
3. **Keep splash images simple** — large or complex SVGs slow the build and may render with artifacts.
4. **Test on real devices** — emulator densities mask icon cropping, especially Android adaptive icon safe zones.
5. **Use composed icons for Android** — `ForegroundFile` + `ForegroundScale="0.65"` ensures the foreground stays within the safe zone.

## Quick Troubleshooting

| Symptom | Likely fix |
|---|---|
| Icon appears blank or white | Check `Color` vs `TintColor`; ensure SVG paths exist |
| Splash shows default .NET logo | Verify `MauiSplashScreen` item is in the `.csproj` |
| Android icon looks clipped | Use composed icon with `ForegroundScale="0.65"` |
| Build error on SVG | Simplify SVG or switch to PNG with `Resize="false"` |
| Icon wrong size on one platform | Set `BaseSize` explicitly in the `.csproj` |

## Checklist

- [ ] `MauiIcon` item exists in `.csproj` with `Color` set
- [ ] `MauiSplashScreen` item exists in `.csproj` with `Color` and `BaseSize`
- [ ] Android: using composed icon with `ForegroundScale` for safe zone compliance
- [ ] SVG sources are simple (no gradients/filters) or PNG fallback with `Resize="false"`
- [ ] Tested on a real device (not just emulator) for density and cropping


---
Source attribution: davidortinau
Original project: https://github.com/davidortinau/maui-skills/blob/79bb4bfd8f671ed0dd97bdf92a36430928e8d984/plugins/maui-skills/skills/maui-app-icons-splash/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 David Ortinau

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: davidortinau
Original project: https://github.com/davidortinau/maui-skills/blob/79bb4bfd8f671ed0dd97bdf92a36430928e8d984/plugins/maui-skills/skills/maui-app-icons-splash/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Frontend Developer, Mobile Developer, Product Manager
Specialties: Frontend, Mobile, Testing
Tools: .Net
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 576ad976d513bfad25add0a19845d11f9d43d67e13331cdd4a571861fe74f34f