01 · failure
Full card + alpha
The opaque card survives as one large shape. Colour detail disappears.
macOS menu bar · source-bound reference
Your tray icon
is not a tiny
app icon.
A macOS template image throws colour away and keeps alpha. Feed it an opaque app-icon card and the card becomes the shape: a black block. The reliable fix is a separate, transparent tray.svg designed to survive at 16 pixels.
The failure, reproduced
Alpha is geometry.
Template images are black plus transparency. macOS supplies the visible colour for the current appearance; the source alpha supplies the silhouette. That is why this failure looks mysterious in a colour editor and obvious once the alpha channel is treated as the drawing.
Full card +
02 · recovery
Full card + auto
auto detects card-like coverage and derives alpha from edge contrast.
03 · preferred
tray.svg + auto
A sparse source keeps intentional transparency and a legible silhouette.
These are not illustrative redraws. The five PNGs on this page are rebuilt from brand/build by iconflow.assemble.to_template; CI compares every byte.
Three rules for a durable template
Draw the silhouette
Use one sparse mark with real transparency around it. At 16 pixels, enclosed holes and separated strokes matter more than colour.
Let macOS tint it
Ship black plus alpha, then inspect the same mask on light and dark menu bars. Do not bake a light-mode or dark-mode colour into the source.
Name the retina pair
Electron recognizes the template convention from filenames: trayTemplate.png and trayTemplate@2x.png.
Accessibility is separate. Keep a real title or label on the menu-bar control. SwiftUI uses the MenuBarExtra title for accessibility even when the visible control is an image.
The exact files IconFlow writes
The colour pair is useful on platforms that accept it. The Template pair is the macOS contract: 16 pixels at standard density and 32 pixels for retina. The optional TypeScript module embeds the same source bytes for Electron projects that prefer an inline asset.
| File | Size | Why it exists |
|---|---|---|
tray/tray.png | 32 × 32 px | Colour tray icon at 2× density. |
tray/tray@16.png | 16 × 16 px | Colour tray icon at 1× density. |
tray/trayTemplate.png | 16 × 16 px | macOS template: pure black plus alpha. The system recolours it. |
tray/trayTemplate@2x.png | 32 × 32 px | Retina template pair. Required, not optional. |
tray/trayIcon.ts | TypeScript | Optional inline data-URL module (--tray-ts). |
The table is read from the same preview_assets path as a real build. If a filename or size changes, this generator cannot silently keep the old answer.
Audit the tray source before ship
A separate source does not guarantee a useful template. Interior colour structure can still collapse into one featureless alpha shape. IconFlow renders the linked tray source through the selected conversion mode and reports when none of its meaningful interior features survive.
iconflow check master.svg \
--tray-svg tray.svg \
--tray-template-mode auto
iconflow review --config iconflow.toml --html review.html
iconflow ship --config iconflow.toml --review master-review.jsoncheck is the early diagnostic. The final ship still re-runs automated QA and requires a current, source-hash-bound review receipt with every human score at least 4 out of 5.
Choose the conversion deliberately
auto- Preserve sparse alpha; derive contrast for a full card. Recommended default.
alpha- Trust source transparency exactly. Best for a purpose-built tray source.
contrast- Always derive the mark from its difference against the background.
Primary platform sources
This guide binds IconFlow behaviour to the platform contracts rather than repeating folklore.
- Apple · NSImage.isTemplateBlack plus clear pixels; alpha controls opacity; the system processes the appearance.
- Apple · MenuBarExtraPersistent menu-bar controls and the accessibility role of the title.
- Electron · TrayTemplate filenames and the recommended 16-pixel / 32-pixel retina pair.
- Electron · nativeImageTemplate-image loading and retina naming behaviour.
Questions people ask
Why is my macOS menu bar icon a black square?
A macOS template image discards colour and uses the source alpha as its shape. If the source is an opaque app-icon card, that alpha says the entire card is the icon, so the system tints a solid block. Use a sparse, transparent tray drawing instead.
What is a macOS template image?
It is a black-and-transparent image that macOS recolours for the current menu-bar appearance. Black supplies the shape, transparency removes the background, and intermediate alpha supplies opacity.
What tray icon sizes should Electron ship on macOS?
Electron recommends a 16 by 16 pixel Template image at standard density and a matching 32 by 32 pixel retina file. IconFlow writes trayTemplate.png and trayTemplate@2x.png, plus colour equivalents.
Does the word Template need to be in the filename?
For Electron's automatic macOS template handling, yes. The base file name must end in Template and the retina pair must keep the same base name before @2x. IconFlow emits those names exactly.
Can I reuse the full app icon in the menu bar?
Usually not. App icons are cards designed for large launch surfaces; menu-bar icons are tiny, transparent silhouettes. IconFlow can derive a contrast mask from an opaque card as a fallback, but a simplified tray.svg is more legible and preserves intent.
What do IconFlow's auto, alpha and contrast modes do?
Alpha preserves the source alpha, which is correct for a genuinely transparent tray mark. Contrast derives transparency from the difference between the mark and its background. Auto keeps alpha for a sparse source and switches to contrast for a full-card source.
How do I test a menu-bar icon on light and dark backgrounds?
Inspect the actual 16 pixel template in both contexts. The system tints the same alpha mask dark on a light bar and light on a dark bar; do not maintain separate coloured artwork for the two appearances.
Does the icon replace an accessible menu title?
No. A graphic is not an accessible name. Give the menu-bar control a real title or label; SwiftUI's MenuBarExtra title is used for accessibility even when the visible control uses an image.
One source for each job.
App card.
Tray silhouette.
One proven family.
Keep the visual relationship, change the geometry for the surface, and let the same review receipt prove both sources.