Problem

Icon work has an awkward middle step. Generating a mark is easy; knowing whether it actually works is not. A logo that reads well at 512px can turn to mush at 16px, and the tools that answer that question usually live somewhere other than the tools that create the asset.

I wanted one surface where I could author a mark by prompt, immediately see it across every real target size, inspect its underlying geometry, fix it in place, and export deterministically — without exporting to another app and losing the SVG as the source of truth.

Technical Architecture

The repo is an npm workspaces monorepo with package-aligned boundaries. preview-app holds the browser application, preview-server runs the HTTP server and handles scaffolding, grounding, manifest, and reload concerns, workflows owns spec indexing and screenshot capture, and image-generation owns the Pillow generators and palette analysis.

The server exposes narrow endpoints for the mutating operations — project scaffolding and rename, grounding image upload, and project color management — so the browser app can persist changes back to disk rather than holding them in memory. The app is a dependency-light vanilla JavaScript client styled with @wintermuted/ui-theme and Lucide icons, using hash-based deep links so any project, asset, or source image is directly addressable.

Mermaid specs are compiled from markdown into a preview index, keeping architecture diagrams in the same review surface as the brand assets.

Key Decisions

Keeping SVG as the canonical source was the constraint everything else followed from. Scripts never overwrite assets/svg/, and outputs/ is treated as disposable generated content. That means any generated artifact can be thrown away and rebuilt, which is what makes the loop safe to iterate in.

Building the editor into the preview app rather than deferring to a general-purpose vector tool was the other significant call. A general tool would be more powerful in isolation, but it would break the loop — the value here is that inspection, correction, and export all happen against the same file the agent just wrote.

Adopting npm workspaces early established package boundaries while keeping existing entrypoints and public commands stable, so the structure could evolve without a second migration.

Challenges

The hardest part was scope discipline. Once the app had a layer tree and geometry fields, it was tempting to keep building toward a full vector editor. I kept the element editor deliberately focused on the operations icon work actually needs — reorder, combine, adjust geometry, adjust color — rather than chasing feature parity with tools that solve a different problem.

Balancing agent-generated output against manual correction also took iteration. The answer was making the manual path cheap: if fixing a generated asset takes seconds, imperfect generation stops being a blocker.

Outcomes

The project is now a working authoring loop rather than a script collection. I can describe a mark in Copilot Chat, watch it appear in the workspace, immediately check it at every size it will ship at, correct its geometry in place, and export deterministic PNGs and review screenshots — all against a single SVG source of truth.

It currently manages several brand and product icon sets, and the rename from wm-asset-workflows to Agentic Icon Builder reflects that shift: from a pipeline that processed assets to a tool that helps design them.