# Icon Vision

> Search, visually compare, select, and integrate icons while designing or implementing UI. Use when Codex builds or edits interfaces that need icons in buttons, toolbars, nav items, tabs, menus, cards, dashboards, empty states, row actions, settings, status indicators, or feature controls; when choosing between icon metaphors; when matching an existing icon system; when sourcing SVG assets or package icons; or when the user asks for icon search, Iconify/Lucide/Heroicons/Tabler/Phosphor/SF Symbols choices, vision-based comparison, best-fit UI icon selection, or accessible icon-only controls.

- Skill: `aihow-to/icon-vision` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aihow-to/icon-vision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aihow-to/icon-vision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aihow-to (https://skillmd.com/u/aihow-to)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aihow-to/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.

```bash
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.