skip-icons

Skip Icons

There is one rule for icons in Skip projects:

Never use Image(systemName:) or Label(_, systemImage:). Always ship a .symbolset resource and render it with Image("name", bundle: .module).

This rule has no exceptions in production code. Every other section of this skill exists to support it.

Why systemName: is an anti-pattern

SwiftUI's SF Symbols catalogue is an Apple-only registry of thousands of glyphs accessed by name. Android has no equivalent registry, and there is no automatic mapping from SF Symbol names to Android Material Icons. So when you write:

Image(systemName: "checklist")
Label("Tasks", systemImage: "checklist")

…the iOS build resolves "checklist" against Apple's SF Symbols catalogue and renders the glyph. The Android build has nothing to resolve "checklist" against and produces a blank space (or a generic placeholder) where the icon should be. The Swift code compiles cleanly on both platforms. The transpiled Kotlin compiles cleanly. Tests pass. The bug only shows up at runtime, on Android, when a human or a Maestro screenshot notices the missing glyph.

Almost every Image(systemName: "...") call you write will fail this way on Android. Examples that ship in real apps and silently break:

Label("Bookmark",  systemImage: "bookmark.fill")          // ❌ blank on Android
Label("Tasks",     systemImage: "checklist")              // ❌ blank on Android
Label("Web",       systemImage: "globe.americas")         // ❌ blank on Android
Label("Code",      systemImage: "chevron.left.forward.slash.chevron.right")  // ❌ blank on Android
Label("Reminders", systemImage: "list.bullet.clipboard")  // ❌ blank on Android
Label("Cloud",     systemImage: "icloud.fill")            // ❌ blank on Android

SkipUI does ship a small hardcoded compatibility map (around 50 names — house, gearshape, magnifyingglass, plus, xmark, trash, and a handful of others) that translates a few common SF Symbol names to Compose Material Icons at runtime. That map exists, but you should still not use systemName: for those names, for three reasons:

1. The list is small and hard to remember. Picking from the safe set requires you to know which 50 names happen to be hardcoded. Pick wrong (e.g. checklist, bookmark.fill, globe.americas) and the Android build breaks invisibly.
2. The rendering isn't identical even when it works. A hardcoded mapping replaces the Apple glyph with a Material Icon that looks similar but isn't pixel-identical. Tinting, sizing, and weight may differ.
3. The map is not a stable API. SkipUI may add or remove entries between releases. A code path that worked yesterday may not work tomorrow.

The solution is to never reach for systemName: in the first place. Use a .symbolset resource for every icon. The same SVG ships to both platforms and renders identically on each.

The internal SkipUI behaviour for systemName: (the ~50-name hardcoded map) is documented in references/sf-symbol-map.md for completeness. That file is descriptive, not prescriptive. It tells you what SkipUI does internally with a systemName: call. It is not a list of names you should be using.

The replacement — Material Symbols in Apple .symbolset format

Apple's .symbolset directory format is a folder containing an SVG plus a Contents.json that Xcode treats as a vector image asset. Google publishes every Material Symbol in that exact format on fonts.google.com/icons. SkipUI's image-asset pipeline ships the same .symbolset bundle to both platforms and resolves it the same way. A single .symbolset works on iOS and Android.

Pick + download

Browse fonts.google.com/icons. The Material Symbols catalogue has ~3000 glyphs covering every common UI need — checklist, bookmark, globe, code, reminders, cloud, all the way out to specialised pictographs. Note the machine name shown for each icon (arrow_back, delete_sweep, home, notifications_active). Underscored, lowercase. You'll use it as the SVG filename and as the Image(...) lookup name.

Use the Apple variant — its SVG contains the Apple symbol-grid metadata. The raw SVG download doesn't, and renders wrong inside a .symbolset. The canonical URL pattern:

https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/<name>/default/<name>_symbol.svg

Download a batch in one pass:

mkdir -p Sources/MyApp/Resources/Icons.xcassets
cd Sources/MyApp/Resources/Icons.xcassets
for name in checklist bookmark globe code reminders cloud add delete check_circle; do
    mkdir -p "${name}.symbolset"
    curl -sS -o "${name}.symbolset/${name}.svg" \
        "https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/${name}/default/${name}_symbol.svg"
done

A symbolset SVG is typically 5–20 KB. A 1 KB download is almost certainly a 404 HTML stub — verify with wc -c and grep -l Symbols *.symbolset/*.svg.

For the per-variant URLs (filled, rounded, sharp), the file-format details, and bulk-Contents.json generation, see references/symbolset-anatomy.md.

Drop into the xcassets

Sources/MyApp/Resources/
  Icons.xcassets/
    Contents.json                # xcassets-level marker — required
    checklist.symbolset/
      checklist.svg
      Contents.json              # symbolset-level — required
    bookmark.symbolset/
      bookmark.svg
      Contents.json

The directory name must end in .symbolset. Both Contents.json files are required. Without the xcassets-level one, SwiftPM ships the SVGs as plain files and Image("checklist", bundle: .module) returns a blank image — without an error. Bulk-generate both with the loop in references/symbolset-anatomy.md.

Reference from SwiftUI

Image("checklist", bundle: .module)
Image("arrow_back", bundle: .module)

Label {
    Text("Share", bundle: .module, comment: "share menu item")
} icon: {
    Image("share", bundle: .module)
}

The string passed to Image(...) is the symbolset directory name without the .symbolset suffix — Image("checklist", bundle: .module) resolves Icons.xcassets/checklist.symbolset/checklist.svg on both iOS and Android.

The localisation-correct shape

The trailing-closure Label { Text } icon: { Image } form is the canonical shape for any labelled icon, because it solves two problems at once:

• Cross-platform icon — the .symbolset resource ships to both platforms via the same module bundle, so the icon renders identically on iOS and Android.
• Translatable label — the String Catalog extractor sees Text(_, bundle: .module, comment:) and adds the string to Localizable.xcstrings automatically.

// ✅ Works on both platforms; localisable; predictable.
Label {
    Text("Bookmark", bundle: .module, comment: "bookmark menu label")
} icon: {
    Image("bookmark", bundle: .module)
}

// ❌ Renders blank on Android; also not translatable.
Label("Bookmark", systemImage: "bookmark.fill")

For the localisation side of the pattern, see skip-localization.

Icon-only buttons (no visible label)

Even when there's no user-facing label text, still use a .symbolset, and attach an accessibilityLabel for VoiceOver/TalkBack:

Button(action: closeAction) {
    Image("close", bundle: .module)
}
.accessibilityIdentifier("button.close")
.accessibilityLabel(Text("Close", bundle: .module, comment: "accessibility label for the close button"))

Image(systemName: "xmark") happens to be on SkipUI's hardcoded list, so it would render on Android — but for the reasons in the previous section, you should still ship a .symbolset. The cost is one ~10 KB SVG; the benefit is a glyph that renders identically and predictably forever.

App launcher icons — skip icon

The Material Symbols workflow above is for in-app glyphs. The launcher icon shown on the home screen / app drawer is a separate artefact:

• iOS — AppIcon.appiconset/ under the app's xcassets, with a Contents.json listing every required size and scale.
• Android — Android/app/src/main/res/mipmap-*/ic_launcher.png plus an adaptive-icon XML.

The Skip CLI generates both from a single source image. The source is a positional argument, not a flag:

skip icon app_icon.png                                       # one PNG for both platforms
skip icon --background "#1A73E8" --inset 0.25 symbol.svg     # SVG overlay on a coloured background
skip icon --background "#5C6BC0-#3B3F54" symbol.svg          # gradient background

SVG, PDF, or PNG inputs are accepted. Re-run whenever the brand changes.

Useful flags:

Flag	Purpose
--background <color>	Background colour or gradient (e.g. #1A73E8 or #5C6BC0-#3B3F54).
--inset <decimal>	Decimal fraction of the canvas to inset the foreground (e.g. 0.25).
--shadow <decimal>	Shadow radius behind the foreground.
--android <path>	Use a different source image for Android.
--darwin <path>	Use a different source image for iOS.
--open-preview	Open the generated icon set in a preview window after generation.

For the full flag list and additional examples, see the skip icon reference.

Workflow for "add a new button with an icon"

Five steps end to end:

1. Pick the glyph at fonts.google.com/icons. Note the machine name (e.g. delete_sweep).
2. Download the Apple-format SVG from fonts.gstatic.com/.../<name>/default/<name>_symbol.svg into Sources/<Module>/Resources/Icons.xcassets/<name>.symbolset/<name>.svg. Verify size > 5 KB and grep -l Symbols succeeds.
3. Write both Contents.json files — the symbolset-level one referencing the SVG, and the xcassets-level marker. Use the bulk script in references/symbolset-anatomy.md.
4. Reference from SwiftUI via Image("<name>", bundle: .module), wrapped in Label { Text(_, bundle: .module, comment: …) } icon: { … } whenever the icon has a visible label.
5. Build with skip app launch and eyeball both platforms. A blank Android icon almost always means the .symbolset directory name doesn't match the Image(...) string, or the SVG isn't the Apple variant. (Or someone reached for systemName: again — search the diff for systemImage: and systemName: and replace each occurrence with the symbolset form.)

Verifying icons render on both platforms

The cross-platform contract for a .symbolset is "shows on iOS, shows on Android, scales/tints with .font(.system(size:)) and .foregroundStyle(...)". Verify by:

• Running skip app launch and eyeballing both screens side by side. A glyph that's blank on Android but visible on iOS is a missing .symbolset or a systemImage: / systemName: call that slipped in.
• For a UI-test suite, the icon-bearing button's .accessibilityIdentifier(...) will work regardless of whether the glyph rendered — but a Maestro takeScreenshot: of the button's region is what catches a blank icon. Capture screenshots into .maestro/screenshots/ and review.

If iOS shows a glyph that Android doesn't:

Symptom on Android	Likely cause
Blank space where the icon should be	An Image(systemName: ...) / Label(_, systemImage:) call. Replace with .symbolset.
Generic placeholder glyph	A .symbolset directory exists but Contents.json references the wrong file.
Glyph appears but is the wrong size/aspect	The SVG is the raw Material download, not the Apple symbolset variant.
Glyph appears but the wrong colour	.foregroundStyle(...) not applied; or the SVG lacks the symbol-grid markers.

Auditing an existing codebase

When picking up a Skip project that was written without the discipline above (often by an agent in a different session, or by a Swift developer not yet aware of Skip's constraints), find every systemName: / systemImage: and replace it:

grep -rn "systemImage:\|systemName:" Sources/

For each hit, pick a Material Symbol with the same meaning at fonts.google.com/icons, download it into the right Icons.xcassets/<name>.symbolset/, and replace the call site:

// Before
Label("Tasks", systemImage: "checklist")
Image(systemName: "bookmark.fill")

// After
Label {
    Text("Tasks", bundle: .module, comment: "tasks tab label")
} icon: {
    Image("checklist", bundle: .module)
}
Image("bookmark_fill", bundle: .module)        // or "bookmark" if you want outlined

Then skip app launch and confirm both platforms now render the glyphs identically.

Cross-references

• The Label { Text } icon: { Image } form is also the localisation-correct shape — see skip-localization for the full String Catalog workflow.
• For where icons fit into the broader SwiftUI-on-Skip surface, see building-skip-ui.
• For verifying that an icon-bearing button responds correctly to user input, see skip-ui-automation — the icon button needs an .accessibilityIdentifier(...) so Maestro can find it whether the glyph rendered or not.
• The internal SkipUI behaviour for systemName: calls (the ~50-entry hardcoded map): references/sf-symbol-map.md. Descriptive only — not a list to pick from.
• The .symbolset directory format, download URL variants, and verification checks: references/symbolset-anatomy.md.