snowyukitty/ai-iconflow

IconFlow

IconFlow turns an app brief and one semantic SVG source into a reviewed, platform-ready icon family.

It is not a stock-glyph generator or a one-off conversion script. IconFlow provides the design constraints, browser-accurate rendering, silhouette-driven bake-off, target previews, hard quality gate, and casebook loop needed to make an icon specific to what an app actually does—and prove that it still works at 16px before shipping it everywhere.

app intent → distinct concepts → SVG master → 16px proof → target family → casebook

Why IconFlow

Most icon pipelines begin after the important decision has already been made. They resize an image, but do not tell you whether the idea is generic, whether a counter closed at 16px, or whether a menu-bar template became a black square.

IconFlow makes those questions part of the build:

| Stage | What IconFlow adds | |---|---| | Intent | A portable iconflow.toml records the user job, essence, personality, palette, clichés, signature device, and targets. | | Explore | A concepting playbook forces 4+ genuinely different lenses and a specific object silhouette (distinctiveness = specificity, not a letter on a tile) before SVG work begins. | | Compare | compare renders finalists at real sizes plus visual silhouettes, so color cannot hide a generic shape. | | Inspect | check catches mechanical risks; review produces a contact sheet and a self-contained Review Lab with actual-size, pixel, adaptive-crop, and target previews. | | Ship | ship fails closed unless automated QA is clean and all six human rubric scores are at least 4/5. | | Learn | Every shipped design becomes structured casebook evidence; case stats reveals recurring weaknesses and house clichés. |

The result is deterministic and fully local. There is no image-model call, API key, or raster lottery: an agent or designer authors editable SVG, and Chromium renders exactly what browsers will display.

Quick start

Python 3.10+ is required. The repository venv is already configured for local development; a fresh environment needs Playwright Chromium once.

python -m pip install -e .
python -m iconflow setup
python -m iconflow doctor

Create the project brief and build contract first:

python -m iconflow init \
  --name "My App" \
  --app-intent "turn scattered research into a decision" \
  --user-job "compare evidence without losing context" \
  --essence proof \
  --personality precise --personality calm \
  --cliche sparkle --cliche checkmark \
  --targets web,tauri,electron,tray

Then follow the design loop instead of jumping straight to export:

# Start from a technique family—not a finished stock logo.
python -m iconflow new flat-geometric --out work/my-app/a.svg

# After diverging, compare 2–3 real finalists and LOOK at the sheet.
python -m iconflow compare \
  work/my-app/a.svg work/my-app/b.svg work/my-app/c.svg \
  --out work/my-app/bake.png

# Promote the winner to master.svg, then prove it.
python -m iconflow check master.svg
python -m iconflow review --config iconflow.toml \
  --out work/my-app/review.png \

Read the 16px pixel zoom, visual silhouette, maskable crops, and target previews.
Score the six axes in the Review Lab only after looking, then export its
`master-review.json` receipt. The receipt binds the decision to the current SVG
and tray-source hashes, project name, selected targets, visual build transforms,
automated-warning state, scores, and notes.

The high-level ship command rejects stale/mismatched receipts, re-runs QA, and
refuses incomplete or sub-4 scores:

python -m iconflow ship --config iconflow.toml \ --review master-review.json