IconFlow

An icon that says what your app does — and is still itself at 16px.
You, or your coding agent, draw one SVG with IconFlow's playbook.
IconFlow compares the finalists at real size, holds the release until a review passes,
then ships favicon, PWA, desktop, and tray files from that one master.

▶ Watch the 45-second film — every pixel in it is real IconFlow output.

Get started · Browse 100 reviewed cases · See how the gate works · Try the free 16px X-ray

_{The X-ray runs in your browser: drop an SVG, PNG, or ICO and see its real 16px pixels and its menu-bar template. No install, no account, nothing uploaded.}

What it catches before your users do

One editable SVG goes in; favicon, ICO, ICNS, PWA, Tauri, Electron, and tray files come out — only after the checks pass.

pip install iconflow          # or: uv tool install iconflow
iconflow setup                # one-time pinned Chromium download — the only network step
iconflow demo --out demo      # doctor → check → review → ship, on a real review

No image model. No API key. No upload. You author the SVG (or your coding agent does), a pinned Chromium renders it exactly as a browser would, and ship fails closed unless automated QA is clean and a human has scored the review sheet at 4/5 or better on all six axes.

The icons you make with it are yours — no attribution, no share-alike, commercial use unrestricted. Run iconflow license for the whole answer.

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

Find your next icon design

Start with the job your icon needs to do, then inspect the evidence:

Watch the quality gate work

^{This is a real capture, not a mock-up. Its checked-in transcript and deterministic renderer make the demonstration reproducible.}

One source. Every surface.

One editable SVG enters, its real pixels are proven at 16px, and the reviewed source ships to favicon, PWA, desktop, and tray.

The site reads in five languages — English, Español, 日本語, 繁體中文, 简体中文. The toolkit and its documentation stay English.

IconFlow is a local design-and-release workflow for agents, designers, and small product teams. It is not a stock-glyph generator or a one-off conversion script: it provides the design constraints, browser-faithful 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.

Twenty structurally different technique scaffolds help designers choose an execution language without pretending a stock shape is a finished identity:

The same packaged sources generate this proof locally with iconflow styles --gallery style-gallery.png; see the style catalog for selection rules, tray strategies, and clean-room research provenance.

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:

The working path is local after dependencies and Chromium are installed. There is no image-model call or API key: an agent or designer authors editable SVG, and a pinned toolchain renders repeatable target assets without network access. Unlike a generic favicon converter, IconFlow starts before conversion—with the product job and competing concepts—and refuses to ship unreviewed pixels.

Five-minute proof

Python 3.10+ is required. The one-time setup step downloads Playwright Chromium; everything after it is local.

pip install iconflow          # or: uv tool install iconflow / pipx install iconflow
iconflow demo --setup --out iconflow-demo

demo --setup fetches Chromium once, copies a real, already-reviewed family, then runs doctor → check → review → ship against its packaged source-bound receipt. Your first success is a genuine gated ship rather than a render. Edit the copied master.svg and re-run ship to watch it refuse the stale receipt.

Working from a checkout instead — contributors, or anyone who wants the brand sources — no activation is required:

git clone https://github.com/snowyukitty/ai-iconflow.git
cd ai-iconflow
python -m venv .venv

# Windows PowerShell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1
.venv\Scripts\python.exe -m iconflow doctor
.venv\Scripts\python.exe -m iconflow ship `
  --config brand/iconflow.toml --review brand/master-review.json `
  --out work/quick-start/icon-out

# macOS / Linux
sh ./scripts/setup.sh
.venv/bin/python -m iconflow doctor
.venv/bin/python -m iconflow ship \
  --config brand/iconflow.toml --review brand/master-review.json \
  --out work/quick-start/icon-out

That last command re-validates IconFlow's checked-in, source-bound review receipt and builds 23 web, Tauri desktop, Electron, and tray files. It is a reproducible engine proof, not a claim that a distinctive new identity can be designed in five minutes.

The same proof is packaged as one command, iconflow demo --out iconflow-demo. It copies the reviewed brand family — master.svg, tray.svg, iconflow.toml, master-review.json — into that directory and runs doctor → check → review (sheet + Review Lab) → ship against the bundled receipt; add --setup to install Chromium first and --json for the machine-readable result. Edit the copied master.svg and re-run ship to watch it refuse the stale receipt.

Design and ship your own icon

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 check master.svg --tray-svg tray.svg   # + macOS template audit
python -m iconflow review --config iconflow.toml \
  --out work/my-app/review.png \
  --html work/my-app/review.html

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

For non-interactive automation, an explicitly approved [review] table in iconflow.toml with the reviewed source_sha256, full contract_sha256, and all six scores ≥4 remains a supported fallback. Any source, project, target, color, Electron, color-scheme, tray-mode, or tray-source change invalidates it.

build remains available as a low-level, deterministic exporter when a caller already owns its quality gate:

python -m iconflow build master.svg --out ./icon-out \
  --targets web,tauri,electron,tray \
  --name "My App" --theme "#191a20" --bg "#fff4e8" \
  --tray-svg tray.svg

Finish by recording the design. This is part of shipping, not optional cleanup:

python -m iconflow case new --slug my-app \
  --project "My App" --targets web,tauri,electron,tray \
  --essence proof --style flat-geometric \
  --device-family ownable-geometry \
  --device "one app-specific signature device" \
  --concept-lens verb-system \
  --cliche "sparkle / checkmark" \
  --first "legibility=3 distinctiveness=4 balance=4 color=5 scalability=3 craft=4" \
  --final "legibility=4 distinctiveness=4 balance=4 color=5 scalability=4 craft=4" \
  --iterations 2 \
  --lesson "Write one reusable, testable rule from the failed pass."

python -m iconflow case lint
python -m iconflow case stats

The proof is visible

IconFlow currently uses Petal Haypile as an explicitly temporary product mark while the permanent identity decision remains open. The owner selected it from the Round 3 living exploration: a low-eared pika returns to its hay store with three oversized petals. Its editable master, linked tray source, source-bound receipt, and checked-in target build live in brand/.

Petal Haypile came out of a 28-direction living exploration. The bake-off sheet below places it beside the four Round 3 finalists that also passed the full target gate, at every native size, in silhouette, and on dark:

Its review sheet is the same artifact every consuming project gets from iconflow review: actual-size renders on three surfaces, pixel zoom, alpha footprint, visual silhouette, and adaptive crops. The case is preserved in casebook/2026-08-14-iconflow-petal-haypile-temporary.md.

Current Petal Haypile rubric: legibility 4, distinctiveness 5, balance 4, color 5, scalability 4, craft 4, check clean. The earlier Flow Gate / Proofed Flow identity remains historical evidence and the fixed specimen used for controlled technique comparisons; its case is casebook/2026-07-13-iconflow-brand.md (historical rubric: legibility 4, distinctiveness 4, balance 4, color 5, scalability 5, craft 5).

Review Lab

review --html writes a self-contained artifact with no remote dependencies. It brings the product brief and the thing being judged into one place:

• real 16–256px actual-size renders plus exact higher-size target transforms, on switchable light, dark, gray, and custom surfaces;
• pixel-zoom views that expose anti-aliasing and closed counters;
• alpha footprint and visual silhouette strips;
• adaptive circle, squircle, rounded, and safe-zone crops;
• browser, PWA, Tauri, Electron, tray, and macOS template contexts;
• automated warnings beside the six-axis human rubric;
• a JSON review receipt for a gated workflow.

The static review.png remains useful in terminals, PRs, and agent sessions. The Review Lab is the deeper decision surface—not a decorative gallery.

What gets built

Targets can be combined; shared sizes render once.

Web builds also support relative/static-site paths, richer manifest metadata, Windows tiles, custom manifest keys, and additional head metadata. See docs/OUTPUT_TARGETS.md for exact file sets.

For products with a full-card app icon, provide a semantic mark-only tray SVG or stable foreground groups. IconFlow's template conversion can separate a contrasting mark from a card, but an explicit tray source is the strongest contract. brand/tray.svg demonstrates the pattern.

Designing bigger: the detail ladder

Every rule IconFlow distilled is a compression rule — survive 16px, own two pixels, one idea. That is why the marks are good, and it is also the ceiling: the drawing that wins a 16px bake-off is, on a 1024px store plate, an under-drawn 16px icon.

The ladder removes the ceiling without forking the source. A group says which size regimes it belongs to, and nothing else changes:

<g data-lod="glyph mark plate"> the one idea, and the whole silhouette </g>
<g data-lod="mark plate">       the second reading                    </g>
<g data-lod="plate">            material: coursing, rim light, glow    </g>

Every built size is then rendered from its own rung — structurally, by deleting what does not belong before the renderer sees it. The shipped favicon.svg carries a generated @media layer that does the same thing in a browser, keyed to the size the SVG is actually drawn at, so one vector file shows its plate in a 512px preview and its glyph in a 16px tab. The two paths are asserted to produce identical PNG bytes at every size, including both rung boundaries.

Adding detail must never become redrawing the logo, so check gates it: the three rungs are rendered at one size and measured for outer footprint, visible shape, optical centre and dominant hue. The one rule the gate enforces is the ladder grows inward — every trait that defines the outer contour stays on the glyph rung.

python -m iconflow ladder master.svg --sheet work/my-app/ladder.png

The proof sheet shows every delivered size beside its rung, the three rungs compared with resolution removed, and a same-mark overlay where coral is geometry the smaller rung invented. A source with no data-lod is flat — a valid answer that behaves exactly as it did before, byte for byte.

Read docs/DETAIL_LADDER.md and the worked example in examples/detail-ladder/, whose README records the chimney collar the overlay caught and why it was removed rather than tuned.

Distinguishable, not merely distinctive: the neighbourhood

Distinctiveness is a ship gate and the worst first-pass axis in the casebook, and it is judged entirely by a human eye — because "is this mark distinctive?" is not a question a tool can answer. "Is this mark distinguishable at 16px from these specific other marks?" is, and it is exactly the test L9 asks a person to run by squinting at a bake sheet: does the silhouette already mean search, settings, home, a bar chart, a letter?

python -m iconflow neighbours master.svg --config iconflow.toml \
  --sheet work/my-app/neighbours.png

Every mark is reduced to a deterministic 16px shape field — a 16×16 grid of occupancy plus pieces, holes, coverage and aspect — and compared by normalised distance against a checked-in, content-addressed index of two corpora: a collision set of deliberately plain generic forms (gear, bell, folder, bar chart, + ✓ # π, letterforms), and IconFlow's own published marks. The radius was calibrated on collisions the casebook had already recorded, not chosen by taste; the docs table also lists what it misses.

A project declares its own sets in iconflow.toml:

[neighbours]
avoid = ["../other-app/master.svg", "@collision"]   # the only set that gates
family = ["../suite/*/master.svg"]                   # supposed to be close; never compared
portfolio = ["../shipped/**/master.svg"]             # three inside the radius is a rut

neighbour-collision gates and names the mark it hit. The bundled corpus can only advise (neighbour-familiar): the house corpus is a mirror, not a wall. The sheet puts the candidate beside its nearest neighbours at real 16px, at 32px, and as the occupancy fields the distance was summed over. It is not a trademark or clearance check, it does not measure distinctiveness, and the human ≥4/5 gate stays exactly where it is.

Read docs/NEIGHBOURHOOD.md and the worked example in examples/neighbourhood/, whose first draft measured 0.07 from a bar chart and was redesigned rather than re-thresholded.

Technique scaffolds, not stock logos

new offers twenty execution families. Discover them from an installed wheel instead of memorizing a list:

iconflow styles
iconflow styles --gallery style-gallery.png
iconflow new cut-paper --out work/my-app/cut-paper.svg

The families span flat geometry, glow, uniform line, mascot, duotone plane, stencil, pixel, isometric, cut paper, enamel, blueprint, stained glass, risograph, clay, cel shading, chrome, ink brush, woodcut, glass stacking, and weaving. Each has its own structural model, 16px rule, and tray/monochrome strategy in docs/STYLE_CATALOG.md.

Each preset renders IconFlow's house structure only to demonstrate the technique. Every file explicitly tells the designer to replace the geometry with the consuming app's user job and one signature device. All twenty pass check cleanly; none is intended to ship unchanged. new preserves an existing output unless replacement is explicit with --force.

The casebook closes the loop

Each case stores the brief, concept lens, device family/detail, clichés avoided, first and final rubric scores, review count, and reusable lessons. Aggregation answers design-system questions that a directory of PNGs cannot:

• Which axis is repeatedly weak on the first pass?
• Is one signature-device family becoming IconFlow's own cliché?
• Are projects improving by the final review?
• Which lessons have not yet been distilled into the playbook or code?

python -m iconflow case list
python -m iconflow case lint --strict
python -m iconflow case stats
python -m iconflow case atlas --out case-atlas.html

The protocol is documented in docs/EVOLUTION.md. Raw experience lives in casebook/; distilled rules live in docs/LEARNINGS.md; mechanically enforceable lessons belong in the engine and its tests.

Repository map

brand/                      IconFlow's own master, tray source, review, and outputs
showcase/                   approved cross-theme masters, receipts, and web builds
website/                    static Cloudflare Pages launch site and reviewed assets
  i18n/                     translation catalogs and the binding glossary (5 languages)
website-redirect/           permanent compatibility redirect for the former host
casebook/                   structured evidence from shipped icons
docs/
  DESIGN_PLAYBOOK.md        geometry, color, 16px discipline, critique loop
  STYLE_CATALOG.md          20 technique families, selection, provenance
  LAUNCH_SITE.md            promotional-site narrative and acceptance contract
  PROMO_VIDEO.md            evidence-led film production contract
  promo/                    source-bound HyperFrames 60/30/15 storyboards
  SHOWCASE_PLAN.md          cross-theme icon production queue
  CONCEPTING.md             divergence, cliché filter, signature devices, bake-off
  REVIEW_CHECKLIST.md       six-axis shipping rubric
  SVG_TECHNIQUES.md         browser-tested SVG construction patterns
  DETAIL_LADDER.md          one source, three size regimes, and the gate that binds them
  OUTPUT_TARGETS.md         exact platform asset contracts
  WORKFLOW.md               config → receipt → gated ship contract
  LEARNINGS.md              distilled rules from shipped cases
  EVOLUTION.md              record → measure → distill protocol
examples/                   end-to-end usage patterns
iconflow/                   renderer, QA, review, packaging, config, and CLI
templates/presets/          check-clean technique scaffolds
skills/                     the agent front door — installed by `iconflow skill install`
  iconflow/                 canonical open Agent Skill + Codex client metadata
  commands/                 /iconflow:icon and /iconflow:setup slash commands
  .claude-plugin/           Claude Code plugin manifest
.claude-plugin/             marketplace catalog for `/plugin marketplace add`
work/                       gitignored design-session evidence
AGENTS.md                   required procedure for agent designers
LICENSES.md                 the tier map: your output, tool, method, works
licenses/                   full CC0 / CC BY / CC BY-SA / CC BY-NC-ND texts

Use IconFlow from your AI agent

IconFlow is built to be handed to an agent. The design procedure, the reference documents it cites, and the gates that stop a generic mark from shipping all travel with the package — so a session in your repository follows the same rules this one does, without cloning anything.

Claude Code — two commands. The plugin carries the skill plus the /iconflow:icon and /iconflow:setup slash commands:

/plugin marketplace add snowyukitty/ai-iconflow
/plugin install iconflow@iconflow

Then just ask for an icon, or run /iconflow:icon a tool that turns scattered research into a decision. The agent installs the toolkit itself the first time.

Codex, Copilot, and other open Agent Skills clients — one command. From any install of the package:

iconflow skill install

That deploys SKILL.md from the installed wheel into ~/.agents/skills/, ~/.claude/skills/, and ~/.copilot/skills/, and removes the superseded ~/.codex/skills/iconflow/ copy (current Codex scans both user roots and does not merge same-named skills, so keeping it would show a duplicate). Add --project to install into the current repository instead, or --dir to name a location. Automatic discovery remains client-dependent.

Any other agent. iconflow skill print writes the whole procedure to stdout, iconflow docs lists every reference document, and iconflow docs CONCEPTING prints one. Nothing requires a checkout:

iconflow docs                        # what is available
iconflow docs DESIGN_PLAYBOOK        # read one
iconflow docs --out ./iconflow-docs  # export the set

The canonical skill source is skills/iconflow/SKILL.md with Codex interface metadata in skills/iconflow/agents/openai.yaml and the Claude Code plugin manifest in skills/.claude-plugin/plugin.json. All three version with the toolkit, and iconflow skill install is the single code path the setup scripts use too, so a deployed copy cannot drift from the source. Edit the canonical file and rerun the installer; never hand-edit a deployed copy.

Agents that prefer a machine surface get the --json envelopes and the 0/1/2 exit codes in docs/AGENT_CONTRACT.md, and can prove the whole engine in one command with iconflow demo --out iconflow-demo.

Calling IconFlow from another project

Install this repository once into the toolkit venv:

path\to\iconflow\.venv\Scripts\python.exe -m pip install -e path\to\iconflow

Then invoke the module from the consuming repository and keep its editable master.svg, iconflow.toml, and case record with that project.

For a Windows shortcut that launches PowerShell, use the high-level helper; it handles nested quoting and verifies CJK paths by reading the .lnk back:

python -m iconflow shortcut \
  --powershell-script "D:\app\launch.ps1" \
  --icon "D:\app\icon-out\build\icon.ico" \
  --workdir "D:\app" --name "My App" \
  --out desktop --content-address-icon

The content-addressed mode installs a SHA-256-named icon alias and implies --verify, so changed icon bytes also change the shortcut's IconLocation instead of relying on Explorer cache invalidation.

Development

python -m pip install -e ".[dev]"
python -m iconflow doctor
python -m unittest discover -s tests
python -m iconflow case lint
python -m build
python scripts/verify_distribution.py dist/*

The engine uses playwright and Pillow; no external service or API key is required. Runtime rendering validates bounded SVG/XML, blocks network and file resources, disables JavaScript and service workers, and freezes animation. See SECURITY.md for the reporting process and THIRD_PARTY_NOTICES.md for dependency and asset provenance. The package, the CLI, the agent skill, and the product are all called iconflow — one name, so pip install iconflow gives you an iconflow command.

Limits and reproducibility

• Installation and iconflow setup need network access; rendering and builds do not.
• Byte-for-byte determinism is scoped to the same normalized SVG, config, and Chromium/Pillow/IconFlow toolchain. Upgrade those components deliberately and review the resulting pixels.
• Tauri output currently covers desktop assets, not Android or iOS launch/icon sets. Tray template extraction is strongest with a dedicated mark-only SVG.
• IconFlow validates and rasterizes SVG; it is not a general-purpose sanitizer for republishing arbitrary source SVG on the web.
• Wheel builds are reproducible when SOURCE_DATE_EPOCH is fixed. Current setuptools sdists have identical file contents across local rebuilds but may differ at the archive level because generated member timestamps vary.

Contributing

See CONTRIBUTING.md for the design/evolution loop, how to run the checks, and the case-recording protocol that keeps the system improving. Release preparation is tracked in docs/LAUNCH_READINESS.md.

License

The icons you make with IconFlow are yours

No attribution, no share-alike, no commercial restriction. Ship them, sell them, trademark them. The technique scaffolds behind iconflow new are CC0 public domain precisely so that a mark you evolve from one inherits nothing, and applying the published method creates no obligation either — copyright covers the playbook's wording, not the design rules it describes.

Run iconflow license any time for the authoritative summary, or iconflow license --json if you are an agent that needs to quote it exactly.

The repository is not under a single license

LICENSES.md is the map; each tiered directory carries its own LICENSE, and full texts live in licenses/.

GitHub's sidebar shows "Apache-2.0" because that is what the root LICENSE file says; it is reporting the tool tier. The written methodology stays open but carries ShareAlike, so a work reusing that prose must credit IconFlow and stay open too. The 137 Living Archive studies and the rest of IconFlow's finished artwork are published as evidence, not as a free icon pack.

One thing IconFlow deliberately copies out is its own identity: iconflow demo materializes the Petal Haypile family to prove the engine against a real receipt, and writes a LICENSE-NOTICE.md beside it saying so. To start your own design, use iconflow init and iconflow new <preset>.

The engine being Apache-2.0 means a modified fork inside a closed product is permitted — that is the deal, and it is what makes the tool safe to adopt. What a redistributor still owes is attribution: Apache-2.0 §4 requires them to keep the license, keep the per-file notices, state that they changed files, and carry NOTICE. Every source file carries an SPDX header so that obligation travels with the code rather than only with the repository. docs/PROVENANCE.md records what that looks like when it is honoured and when it is not.

Contributions need a DCO sign-off and a signature on CLA.md. You keep your copyright; the CLA is a license, not an assignment, and its purpose is stated openly in its §6.

Attribution lives in NOTICE; dependency provenance in THIRD_PARTY_NOTICES.md.

No license here grants permission to use the IconFlow name, logo, or official project identity to brand or endorse a modified distribution, product, or service. Truthful references and compatibility statements remain welcome; see the IconFlow trademark policy for the precise boundary.