Spec — Icon generation targets (per-platform output rules)

Applicability

Every icon shipped by a Koder module. Source of truth for kicon generate (see dev/kicon). Human readers consult this when reasoning about why a specific file exists; machines consult the tool, which *ncodes these rules in code*— no drift is possible when apps use kicon.

Master SVG prerequisites

See meta/docs/stack/specs/icons/products.kmd. This spec assumes the master SVG is valid per that contract (viewBox 0 0 512 512, no background rect, content within inner 66 % circle, ≥ 4 % margin).

Target matrix

android

Covers both the legacy ic_launcher bitmaps (Android ≤ 7) and the adaptive-icon foreground for Android 8+.

Legacy bitmaps also emitted as ic_launcher_round.png with a soft mask (rounded-square corner mask applied at raster time).

linux

FreeDesktop hicolor icon theme.

Slug = kicon.toml slug field or the module directory name.

web

store

Koder Hub listing. Full-canvas display, no launcher cropping.

flutter-app

Embedded asset PNGs that a Flutter app loads via Image.asset('assets/icons/<slug>.png'). Distinct from the android target, which writes platformlauncher mipmaps. This is the inbundle asset every widget call site (AppBar logo, splash screen, settings header, system tray via tray_manager, Linux update notifications via local_notifier's AssetsLinuxIcon) renders with the app icon.

Detection: emitted only when <module>/app/pubspec.yaml exists OR <module>/app/assets/icons/ already exists. On non-Flutter modules the generator returns silently with zero emissions, so it can sit in the default target list without surprising side-effects.

Aliases: <module>/kicon.toml may declare additional names, byte- identical copies under each alias name. Used to keep widget call sites stable across rebrands (e.g. koder-hub.png → khub.png):

[targets.flutter-app]
aliases = ["koder-hub", "hub"]

Spec authority: productsdevkicon#020. Origin: Hub v2.30.0/v2.30.1 shipped a new launcher with a stale AppBar logo because nobody re-generated the asset PNG (manual cp was the only path).

ios (v0.2 — deferred)

Full AppIcon.appiconset with 20+ sizes for iPhone / iPad / Spotlight / Notification / Settings / App Store (1024×1024). No alpha (iOS fills the background white or per-app tint).

macos (v0.2 — deferred)

.icns bundle with ic07 (128×128), ic08 (256×256), ic09 (512×512), ic10 (1024×1024), plus Retina variants ic11ic12ic13/ic14.

windows (v0.2 — deferred)

.ico file embedding 163248/256 PNG images.

Background handling per target

Validation that must pass before generation

All of these run in kicon validate; kicon generate refuses to emit without a clean validation pass unless --force is set (CI only).

1. *argin*(Error): rendered bbox leaves ≥ 4 % (20 px) on every side

   of the 512 canvas. Matches products.kmd §2 ("centralização óptica com tolerância ±4px"). This is the master-level margin contract.

2. *o background rect*(Error): no root-level opaque <rect> that

   fills the full canvas.

3. *quare viewBox*(Error): viewBox="0 0 N N" with identical width

   and height.

4. *o size attributes*(Warning): absence of width="" and

   height="" that force non-square rendering; SVG should scale to any target size.

5. *afe-zone*(Warning): rendered content bbox fits within the inner

   66 % circle (r = 512 × 0.33 = 169 px from center). The Material Adaptive Icon safe zone is a target-level constraint, not a master-level one — kicon generate enforces it for ic_launcher_foreground.png / ic_launcher_monochrome.png by wrapping the master at 66.67% of the canvas (16.65% transparent margin on every side). Masters legitimately fill ~92 % of the canvas per products.kmd §2; the Warning surfaces masters whose content would still clip after wrapping (e.g. content centered well off the canvas center). Promoted to Error would block every existing product.

Canonical reference

• products/dev/kicon/cmd/kicon/main.go — the Go reference implementation.
• `productsdevkiconinternaltargets