icon-toolkit

name	icon-toolkit
description	Collect, evaluate, and prepare icon assets for draw.io diagrams, academic paper figures, PPT slides, and frontend design. Use when the user needs SVG or transparent PNG icons, wants to extract site icons or logos, compare candidate assets, convert formats, or prepare icons for publication-quality or design-quality output.

Icon Toolkit

Use this skill to obtain icons that are actually usable in diagrams, papers, slides, and UI work. Prefer SVG when possible. Prefer remote icon libraries first; treat favicon fetching as only one fallback acquisition path, not the whole job.

Quick decision tree

• For draw.io: prefer clean SVG; otherwise transparent PNG at adequate resolution.
• For paper figures: prefer SVG or PDF-style vector output; avoid blurry raster icons.
• For PPT: prefer SVG first, transparent PNG second.
• For frontend/UI: prefer optimized SVG with sensible viewBox, width/height handling, and simple fills/strokes.

Workflow

1. Identify the target use case: draw.io, paper, PPT, or frontend.
2. Search remote icon libraries first for clean SVG assets.
3. If remote libraries do not have a suitable result, acquire candidates from the website, provided files, or raw SVG sources.
4. Prefer vector sources over raster sources.
5. Compare candidates for clarity, background transparency, editability, and style fit.
6. Convert or clean the chosen asset only as much as needed.
7. Deliver the output in a format appropriate for the user’s actual destination.

Remote libraries first

Use these before scraping a site when the user wants a brand logo or a common UI icon:

• scripts/pick_icon.py <query> --target <target> --out-dir <dir> for the default one-shot flow
  • Add --list-only to inspect candidates without downloading in a human-friendly summary format
  • Add --prefer-source simple-icons|iconify to bias source selection
  • Add --pick N|auto-brand|auto-ui to control selection strategy
  • Add --name <basename> to customize output naming
  • This flow writes manifest.json, metadata.json, and candidates.json
• scripts/search_remote_icons.py <query> for the main ranked remote search flow
• scripts/search_iconify.py <query> for raw Iconify-only search
• scripts/search_simple_icons.py <query> only if you are specifically iterating on Simple Icons lookup behavior
• scripts/fetch_remote_icon.py <url> --out <file> to save the chosen SVG locally

Prefer this order:

1. pick_icon.py for normal use
2. search_remote_icons.py when you want ranked candidate review first
3. search_iconify.py when you want broader raw results
4. Website extraction only when library results are missing or unsuitable

Acquisition

From a website

Start with scripts/fetch_site_assets.py <url> to collect icon, logo, manifest, and common-path candidates. Use ../icon-fetcher/scripts/fetch_icon.py only when a quick favicon-style fetch is enough. If the quick result is too small or wrong, inspect the richer candidate list for:

• inline SVG logos
• image tags pointing to brand assets
• manifest-linked icons
• asset directories with larger PNG or SVG files

From user-provided files

Inspect the file type first. If the user already has SVG, keep it vector unless the target app forces raster output.

Output rules by target

draw.io

• Deliver SVG when possible.
• If raster is required, use transparent PNG and avoid tiny favicon-sized assets.
• Prefer simple silhouettes and recognizable shapes over decorative detail.

academic papers

• Prefer SVG.
• If journal tooling is fragile, also provide a PNG fallback.
• Favor monochrome or visually restrained variants when the icon sits inside a scientific figure.
• Avoid busy gradients unless the user explicitly wants brand-accurate artwork.

PPT

• Prefer SVG because it scales and is easy to recolor.
• If SVG fails in the user’s presentation tool, provide transparent PNG fallback.
• Keep backgrounds transparent.

frontend

• Prefer SVG.
• Keep the markup simple.
• Preserve or normalize viewBox.
• Remove unnecessary metadata/comments if editing manually.

Quality heuristics

When choosing among candidates, prefer in this rough order:

1. SVG with clean geometry
2. large transparent PNG
3. apple-touch-icon or high-res PNG favicon
4. classic .ico favicon as fallback only

Reject or downgrade assets that are:

• blurry
• opaque-background when transparency matters
• tiny favicon-only rasters for print or slides
• visually inconsistent with the surrounding design

Practical script flow

1. For the normal case, run scripts/pick_icon.py <query> --target <drawio|paper|ppt|frontend> --out-dir <dir>.
2. If you want to inspect candidates first, run scripts/pick_icon.py <query> --list-only.
3. If you want to bias brand/logo picks, add --prefer-source simple-icons; if you want general library-first behavior, add --prefer-source iconify.
4. If you want manual review before downloading, run scripts/search_remote_icons.py <query> and then scripts/fetch_remote_icon.py <url> --out <file>.
5. If remote results are weak or unavailable, optionally inspect raw Iconify results with scripts/search_iconify.py <query>, then run scripts/fetch_site_assets.py <url> to gather site-based candidates.
6. Run scripts/score_icon_candidates.py <candidate1> <candidate2> ... to rank likely winners.
7. Run scripts/download_candidates.py --json-file <file> --out-dir <dir> or download selected assets manually.
8. If the chosen asset is SVG, run scripts/clean_svg.py <src.svg> --out <cleaned.svg> for a simple cleanup pass.
9. If the site uses inline SVG logos, run scripts/extract_inline_svg.py <url> --out-dir <dir>.
10. If raster fallback is needed and a renderer exists, run scripts/render_svg_fallback.py <src.svg> --out <fallback.png> [--width N].
11. Run scripts/prepare_icon_variants.py <file> --target <drawio|paper|ppt|frontend> --out-dir <dir> to make destination-specific handoff files.

References

• Read references/usage-patterns.md when the user’s destination format matters.
• Use scripts/pick_icon.py for the default one-shot acquisition and preparation flow.
  • Expect output files plus manifest.json, metadata.json, and candidates.json in the output directory.
  • Expect target-specific final names such as *-icon-frontend-ready.svg, *-icon-ppt-ready.svg, or *-icon-drawio-ready.svg.
• Use scripts/search_remote_icons.py for the default ranked remote search flow.
• Use scripts/search_iconify.py for broad remote icon search.
• Use scripts/search_simple_icons.py only for targeted Simple Icons iteration/debugging.
• Use scripts/fetch_remote_icon.py to download chosen remote assets.
• Use scripts/score_icon_candidates.py to compare icon URLs or local files.
• Use scripts/fetch_site_assets.py to enumerate richer site asset candidates, including manifest icons.
• Use scripts/download_candidates.py to save multiple candidates locally for review.
• Use scripts/clean_svg.py for basic SVG cleanup before frontend/design handoff.
• Use scripts/extract_inline_svg.py to pull embedded logo/icon SVGs into standalone files.
• Use scripts/render_svg_fallback.py to produce PNG fallback files when rsvg-convert or inkscape is available.
• Use scripts/prepare_icon_variants.py to create per-target output copies with warnings.

Notes

• Keep transformations minimal and reversible.
• If the user asks for “usable in design,” do not stop at downloading favicon.ico.
• If the user asks for brand fidelity, keep official colors and proportions.
• If the user asks for paper-figure cleanliness, prefer simplified monochrome variants.
• If the user needs multiple deliverables, provide both the original best asset and a target-specific handoff copy.
• For frontend or publication use, prefer a cleaned SVG plus one fallback raster file when practical.
• If a site hides its best logo in inline SVG instead of a favicon path, extract the inline SVG before settling for raster assets.