App Icon Gen

Create local review assets and reusable app icon packages from a JSON spec. The normal route is semantic layered authoring: a small set of meaningful SVG/base-shape layers or deliberately clean PNG fallback layers, rounded preview assets, unrounded app/source assets, separated .icon assets when needed, and verification evidence.

This skill may export rendered PNGs with Icon Composer's bundled ictool when it is locally available on macOS. It does not prove app integration or final platform rendering beyond those exported PNG files.

Hard Contract

For every new or repaired icon, use one generation root: the user-facing delivery directory.

• Write the current spec at <delivery>/tmp/work/spec.json before generation.
• When a user source image/vector or selected generated concept exists, keep exactly one visible source evidence file at <delivery>/<delivery-name>.origin.png or <delivery>/<delivery-name>.origin.svg; put unselected candidates under <delivery>/tmp/work/.
• Put every intermediate artifact under <delivery>/tmp/work/ as it is created: masks, threshold tests, extracted foregrounds, traced candidates, comparison images, notes, and repair scratch.
• Generate with author-icon --spec <delivery>/tmp/work/spec.json --out <delivery>.
• Reruns may overwrite generated root files, layers/, .icon/, apple/, and tmp/reports/; they must preserve existing tmp/work/ except for replacing tmp/work/spec.json with the current spec, and preserve .origin.png/.origin.svg unless the selected source changes.
• Do not generate a full package in another directory and reorganize or copy it into the delivery directory.
• Do not patch generated layers/, .icon/Assets, or icon.json; update the spec and regenerate.

Normal delivery layout:

<delivery>/
  <delivery-name>.preview.svg
  <delivery-name>.preview.png
  <delivery-name>.svg
  <delivery-name>.png
  <delivery-name>.origin.png or <delivery-name>.origin.svg  # when source evidence exists
  <Name>.icon/
  apple/                              # when macOS Icon Composer ictool is available
    iOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    macOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    watchOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
  layers/
  tmp/
    reports/
    work/
      spec.json

The visible delivery root must stay limited to .svg, .png, .preview.svg, .preview.png, .origin.png, .origin.svg, .icon, apple/, layers/, and tmp/.

Workflow

1. Inspect supplied sources before asking questions: attachments, paths, app metadata, existing assets, screenshots, SVG/logo files, .icon bundles, and project-local source vectors.
2. Choose one route: source conversion, generated concept to package, direct semantic authoring, or existing .icon refinement.
3. Read only the route-specific references below.
4. Write or update <delivery>/tmp/work/spec.json; keep layers in bottom-to-top visual order. If source evidence exists, copy the selected source or concept to <delivery>/<delivery-name>.origin.png or <delivery>/<delivery-name>.origin.svg.
5. Generate directly into the delivery directory. On macOS, if Icon Composer.app's ictool exists under /Applications/Icon Composer*.app or /Applications/Xcode*.app/Contents/Applications/Icon Composer.app, author-icon also writes 1024px rendered PNG products under apple/.
6. Run verify; add --reference when a reference image exists. Normalize the reference first only when its canvas/size/mask differs from the preview canvas.
7. Inspect generated preview/app assets, .icon/Assets, icon.json, reports, and the applicable verification evidence ladder before completing or changing route.
8. If verification or inspection fails, repair the spec, regenerate, and verify again.

Run commands from the skill directory, or use an absolute --prefix to scripts/. Node package metadata lives in scripts/package.json; do not run npm install at the skill root.

npm --prefix scripts ci

delivery="/absolute/path/to/my-icon"
mkdir -p "$delivery/tmp/work"

npm --prefix scripts run author-icon -- \
  --spec "$delivery/tmp/work/spec.json" \
  --out "$delivery"

npm --prefix scripts run verify -- --out "$delivery"

With a reference:

npm --prefix scripts run verify -- \
  --out "$delivery" \
  --reference "/absolute/path/to/reference.png"

Use absolute paths for script inputs and outputs.

Verification Evidence Ladder

Do not repair or switch routes from side-by-side and mean delta alone. Choose evidence by failure type and use it before changing the spec:

• Whole-icon likeness: inspect reference-side-by-side.png first for overall style, scale, mass, and obvious drift.
• Geometry, placement, proportion, and layer alignment: inspect reference-overlay.png before deciding a foreground is shifted, too small/large, or the wrong shape.
• Color, background, glow, shadow, antialiasing, and material drift: inspect reference-diff.png and the verifier diagnostics before changing fills or adding/removing material.
• Rounded app-mask/frame drift: treat frame_or_rounded_mask_residual_dominated as frame normalization evidence rather than foreground shape failure; inspect the interior diff before repairing the mark.
• Severe local mismatch: read local_sample_gate, local_samples, and tile_heatmap; translate hotspots into a concrete repair hypothesis instead of treating them as another score.
• Smooth symbolic marks, mascots, loops, ribbons, and brand-like contours: use overlay/diff plus bbox/centroid or shape-facts when the visual error is ambiguous.
• Simple SVG primitives: run geometry-audit on the affected layer after repair; a numeric pass does not excuse wobbly curves, bad tangents, or path noise.
• PNG fallback: inspect the isolated PNG asset and png_layer_hygiene; reference mean success is not enough.

Repair order for reference-driven work: geometry/placement first, then scale/proportion, then color/background, then renderer/material differences. Only choose PNG fallback after the relevant SVG route has failed with evidence from overlay/diff/local diagnostics or isolated asset inspection; for clean separable silhouettes, the relevant SVG route includes component-level traced SVG before PNG fallback.

Reference Routing

• references/source-requirements.md: provenance, identity risk, source classification, background route, and PNG fallback risk.
• references/concept-prompts.md: no source artwork exists and image generation or direct concept authoring is needed.
• references/semantic-icon-design.md: JSON design contract shared by no-reference image generation and direct semantic authoring.
• references/style-directions.md: SVG-convertible style directions for semantic_icon_design.
• references/semantic-authoring.md: JSON spec structure, semantic_review, source_analysis, layer order, text, and PNG fallback decisions.
• references/cookbook.md: route is ambiguous or the icon matches a known family such as geometric marks, letterforms, text, material references, or overlapping plates.
• references/icon-composer.md: .icon structure, fill formats, Icon Composer material boundaries, asset formats, and icon.json.
• references/verification.md: verifier behavior, reference comparison, visual-review sidecars, batch summaries, and completion status.
• references/optimization-methods.md: geometry polish, bitmap extraction, shape diagnostics, localized repair, or foreground cleanup.
• references/failure-modes.md: dirty PNGs, wrong semantics, preview/fill drift, source-vector needs, path repair, or misleading numeric passes.
• references/golden-examples.md: small known-good specs and anti-patterns.
• examples/semantic-image-prompts/README.md: index of no-reference image prompt examples; read only the matching example file after choosing a style direction.

Completion Gate

Complete only when all applicable checks are true:

• Required root assets, layers/, .icon/, tmp/reports/style-report.json, and tmp/work/spec.json exist.
• When a source/reference/generated concept drove the package, <delivery-name>.origin.png or <delivery-name>.origin.svg exists at the delivery root and is not imported into .icon/Assets.
• tmp/reports/package-verification.json.outcome.completion_status is "complete_candidate".
• Preview SVG/PNG are the rounded local visual contract; root SVG/PNG are the unrounded app/source canvas.
• apple/ exports, when present, are generated products rather than verify gates.
• .icon/Assets contain clean source assets, not a single full rendered app icon unless the accepted route is a documented PNG fallback.
• svg_material_warnings and png_layer_hygiene are empty or explicitly accepted with evidence.
• For reference matching, side-by-side, overlay, and diff were generated and inspected; overlay/diff/local diagnostics were used to justify any repair or route change; mean delta, visual_delta_gate, and local_sample_gate either pass the route target or the accepted semantic tradeoff is recorded.
• No simple background is duplicated into .icon/Assets; no preview-only rim, glow, bevel, shadow, highlight, border, or mask artifact is imported as source material.

Do not widen completion into Icon Composer import, app integration, publication, or platform-specific final rendering unless the user explicitly asks for that.

Final response must include the delivery path, source evidence file when applicable, .icon asset formats, completion_status, reference mean delta when available, visual delta gate and local sample gate when available, svg_material_warnings, png_layer_hygiene, and whether side-by-side/overlay/diff/assets were inspected.