Icon Vision

Icon Vision

Operating Rules

1. Respect the system.

   • Inspect the repo first with rg for icon imports, wrappers, stroke widths, sizing, and package conventions.
   • Use the existing icon family before adding raw SVGs. Prefer package imports over copied assets.
   • For native Apple UI, prefer SF Symbols via Image(systemName:), UIImage(systemName:), or equivalent. Use Iconify for web, cross-platform, or custom assets.
   • For branded icons, product logos, and store badges, use official brand sources; do not substitute generic icons.

2. Choose the family before the glyph.

   • First decide the icon system that belongs in the product: existing repo family, native platform symbols, design-system icons, or a single package family.
   • Default to the host system when obvious: SF Symbols for native Apple UI, Material Symbols for Material/Android UI, Heroicons for Tailwind UI, existing package icons for established apps.
   • Use Iconify broadly to scout the landscape, then narrow to one family with --collections once the visual voice is chosen.
   • Prefer one icon voice per surface. Mix families only when the chosen family clearly fails for a needed concept, and document why.
   • Treat the script's default ordering as a search bias, not a design decision.

3. Search hypotheses, not word salad.

   • If the metaphor is not obvious, run 2-4 conceptually distinct searches: literal object, user action, UI convention, state/result, adjacent metaphor.
   • Keep one concrete concept per query and one contact sheet per concept. Use vision to choose across sheets.
   • Prefer the UI meaning over the button label: item deletion -> trash, not delete.
   • Example: for "AI improve this text," compare sparkles, wand, edit, pen, stars, and magic as separate searches.

4. Inspect visually at real sizes.

   • Generate candidates with scripts/iconify-scout.mjs.
   • Inspect contact-sheet.png with view_image before choosing. Judge the 16/20/24/32 px previews first.
   • If no PNG appears on macOS, run qlmanage -t -s 1800 -o <out> <out>/contact-sheet.svg, then inspect the generated PNG.

5. Choose the quietest clear symbol.

   • Prefer clarity at a glance, consistency with surrounding symbols, one dominant idea, correct apparent weight, enough negative space, and graceful behavior at 16-24 px.
   • Reject icons that need explanation, mix visual weight, rely on text, contain unnecessary perspective, use fixed multicolor styling without reason, or read as branded when the control is generic.
   • Check directionality for arrows, navigation, media, undo/redo, reply/forward, import/export, and similar controls.
   • Add accessible labels for icon-only controls; do not rely on color alone for state or danger.
   • Consider no icon when the label alone is clearer.

6. Integrate minimally.

   • Import the selected package icon when the project supports it.
   • Copy standalone SVGs only when needed, preserving currentColor unless fixed color is intentional.
   • Report the selected icon id, source URL, destination/import path, accessibility label if relevant, and key rejected alternatives.

Iconify Scout

Use Iconify to compare candidates and source SVGs; implement with the project's chosen icon system whenever possible.

node ~/.codex/skills/icon-vision/scripts/iconify-scout.mjs \
  --query "sliders" \
  --out work/icon-scout/sliders \
  --limit 48 \
  --style outline \
  --context web

Options:

• --query: Required. Use one concrete search concept.
• --out: Required. Writes SVGs, candidates.json, contact-sheet.svg, usually contact-sheet.png, and decision.md.
• --limit: Candidate count. Default 48.
• --style: outline, filled, or any. Default outline.
• --context: general, web, or apple. Use apple for Apple-adjacent visual judgment while still preferring SF Symbols for native Apple UI.
• --collections: Optional comma-separated prefixes such as lucide,heroicons,tabler,ph,iconoir,radix-icons,material-symbols,mdi.

After running:

1. Read <out>/decision.md.
2. Inspect <out>/contact-sheet.png with vision.
3. Pick by visual fit, then use <out>/candidates.json for the local SVG path and source URL.