Icon Generation Targets

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 encodes 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 platform-launcher mipmaps. This is the in-bundle 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.

dark variants — icon-dark.svg (iOS 18 dark / Android 13+ themed)

A module MAY ship an optional second master icon-dark.svg alongside icon.svg (same dir, same viewBox). When present, the ios and android targets emit dark/themed variants from it; when absent, nothing extra is emitted (no warning). The dark master faces the same validation gate as the light master (safe-zone, margin, bg-rect) — a violation FAILs the generate exactly like the light master (override via --force / --allow-out-of-safe-area).

Design: detection is by presence of icon-dark.svg (no separate target enum / koder.toml flag) — a module either ships the second master or it doesn't. --check parity includes the dark artefacts. Webdesktopwindows have no dark icon variant (those surfaces theme the surrounding chrome, not the launcher icon).

verge-symbols — UI glyph-set family target

Family-level, not per-module. Every target above generates a single product/launcher icon from one master SVG. This target is the odd one out: it generates the whole Verge Symbols UI glyph family (the flat monochrome glyph set — specs/icons/ui-symbols.kmd) once from the inventory of source glyphs, producing the artifacts every Koder UI consumes via KoderIcon. It is invoked for the Verge Symbols family itself, not for each product.

Input (not a single master SVG): the glyph source set listed in meta/brand/koder-design/symbols/glyph-inventory-v1.kmd (140 glyphs v1), one source SVG per glyph, drawn per the ui-symbols.kmd geometry (grid 24, fill-flattened, per-opsz masters @ 162024).

Outputs (per ui-symbols.kmd §R8):

Codepoint assignment: stable Private-Use-Area range, assigned by glyph name (the inventory is the contract), append-only across versions — a glyph never changes codepoint (policies/always-on.kmd). The assignment map is emitted to dist/codepoints.json and is the source of truth re-read on every regen (never reassigned).

Ligatures (additive, kicon#041): the .woff2/.ttf also carries a GSUB liga lookup mapping each glyph name (kebab/snake) + its R10.2 aliases to the glyph, so typing the name renders the icon (Material parity). The PUA codepoint stays the canonical delivery (ui-symbols.kmd §R8); ligature is an opt-in convenience layered on top — component glyphs are blank zero-advance glyphs cmap'd by their ASCII code (no collision with the PUA block). Built by build_font.py (_add_ligature_gsub); regression build_font_test.py.

Background: transparent always; currentColor / fill=none root for runtime theming (ui-symbols.kmd §R7). No flatten-to-white (glyphs are never favicons).

Status: deferred until the family exists (meta/brand/koder-design

033). This section specifies the target rules so dev/kicon can

encode them; the generator has nothing to emit until the source glyphs are drawn. The KoderIcons Dart output feeds koder_kit #071.

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. Margin (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. No background rect (Error): no root-level opaque <rect> that

   fills the full canvas.

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

   and height.

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

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

5. Safe-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. Masters legitimately fill ~92 % of the canvas per products.kmd §2, so this warns on every Koder master and is downgraded per-icon by [icon].allow_out_of_safe_area. Promoted to Error would block every existing product.

Adaptive-foreground fit (data-adaptive-fit, kicon#051). How the ic_launcher_foreground.png / ic_launcher.png / ic_launcher_monochrome.png PNGs handle the safe zone is declared by the master, never inferred (mirrors §2.2 data-keyline):

• default (attribute absent): full-bleed — the master passes

  through at full canvas and its own §R7 design margin provides squircle safety. This is kicon#041's owner-ratified default.

• data-adaptive-fit="safe-zone": the artwork's true reach (max

  distance from centre to any opaque pixel, alpha ≥ 200 — drop-shadow ignored) is scaled onto the safe radius (0.33·canvas), so it clears every OEM launcher mask. Declared by corner-/edge-filling silhouettes that would otherwise overflow an aggressive squircle (the Koder Hub honeycomb: its hexagonal hull reaches r≈205 while its bbox corners sit empty — the §2.2 case a flat fraction or bbox-fill mis-handles).

Reach (not bbox) is measured, so a non-rectangular hull nests as large as the safe circle allows. The earlier flat adaptiveSafeZoneFraction constant (0.6667 → 0.55 → 1.0) is retired: a single fraction conflates the wrapper margin with the master's built-in margin, so no value ever fit every icon.

verge-symbols validates by a different rulebook. The checks above are for product-icon masters (512 canvas, adaptive-icon safe-zone). The glyph-set target validates each glyph per ui-symbols.kmd §R8 instead — Error: fits canvas 24 with trim ≥ 2px, PUA codepoint unique + stable, R10 naming, outer stroke edge on whole pixel @16/@24; Warning: keyline anchoring (± overshoot), round cap outside the closed motion list, legibility @16. The 512/safe-zone rules do not apply to glyphs.

Canonical reference

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