mcpField
M
maui-app-icons-splash

maui-app-icons-splash

github.com/davidortinauDesign & UI17652 installsUpdated 16w ago
Repository

About maui-app-icons-splash

.NET MAUI guidance for developers configuring app icons and splash screens. It focuses on Android safe zones, SVG sizing and build-time rendering pitfalls.

Key features

  1. 01Icon and splash configuration checks
  2. 02Android adaptive icon safe-zone guidance
  3. 03SVG and PNG troubleshooting
  4. 04BaseSize sizing guidance
  5. 05Real-device testing checklist

Use cases

  1. 01Diagnose blank or clipped icons
  2. 02Resolve SVG build rendering issues
  3. 03Correct platform-specific icon sizing
  4. 04Check splash screen project configuration

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/davidortinau/maui-skills --skill maui-app-icons-splash

After installing, type/maui-app-icons-splashin Claude Code to confirm it loaded.

Bundled filesreferences/icons-splash-api.md

Details

From the project README

.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.

<!-- ❌ 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.

<!-- ❌ 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.

<!-- 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.

<!-- 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

SymptomLikely fix
Icon appears blank or whiteCheck Color vs TintColor; ensure SVG paths exist
Splash shows default .NET logoVerify MauiSplashScreen item is in the .csproj
Android icon looks clippedUse composed icon with ForegroundScale="0.65"
Build error on SVGSimplify SVG or switch to PNG with Resize="false"
Icon wrong size on one platformSet 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

Comments

Markdown supported