Icon Design

Select the right icon for the job. Maps concepts to icons across three modern libraries, provides ready-to-use templates, and prevents common mistakes like broken tree-shaking and inconsistent styles.

Quick Reference

Concept	Lucide	Heroicons	Phosphor
Award/Quality	`Trophy`	`trophy`	`Trophy`
Price/Value	`Tag`	`tag`	`Tag`
Location	`MapPin`	`map-pin`	`MapPin`
Expertise	`GraduationCap`	`academic-cap`	`GraduationCap`
Support	`MessageCircle`	`chat-bubble-left-right`	`ChatCircle`
Security	`Shield`	`shield-check`	`Shield`
Speed	`Zap`	`bolt`	`Lightning`
Phone	`Phone`	`phone`	`Phone`
Email	`Mail`	`envelope`	`Envelope`
User/Profile	`User`	`user`	`User`
Team	`Users`	`user-group`	`Users`
Settings	`Settings`	`cog-6-tooth`	`Gear`
Home	`Home`	`home`	`House`
Search	`Search`	`magnifying-glass`	`MagnifyingGlass`
Check/Success	`Check`	`check`	`Check`
Close/Cancel	`X`	`x-mark`	`X`
Menu	`Menu`	`bars-3`	`List`
Calendar	`Calendar`	`calendar`	`Calendar`
Clock/Time	`Clock`	`clock`	`Clock`
Heart/Favorite	`Heart`	`heart`	`Heart`

Library Selection

Library	Best For	Package
Lucide	General use, React projects	`lucide-react`
Heroicons	Tailwind projects, minimal style	`@heroicons/react`
Phosphor	Weight variations needed	`@phosphor-icons/react`

Default recommendation: Lucide (1,600+ icons, excellent React integration, dynamic loading via lucide-react/dynamic).

Selection Process

Identify the concept -- what does the label/title communicate?
Check semantic mapping -- see references/semantic-mapping.md
Choose library -- Lucide (default), Heroicons (Tailwind), Phosphor (weights)
Apply template -- see references/icon-templates.md
Verify consistency -- same style, same size within each section

Icon Style Rules

Rule	Detail
No mixed styles	Use all outline OR all solid in a section
No emoji	Use proper icon components (tree-shakeable)
Use currentColor	Icons inherit text color via `stroke="currentColor"`
Semantic colors	Use `text-primary`, not `text-blue-500`
Consistent sizing	Inline `w-4 h-4`, cards `w-8 h-8`, hero `w-10 h-10`
Tree-shaking safe	Use explicit named imports and icon maps, never `import *`
Accessibility	Add `aria-hidden="true"` to decorative icons, `aria-label` to buttons

Common Mistakes

Mistake	Correct Pattern
Importing all icons with `import * as Icons` breaking tree-shaking	Use explicit named imports and a static icon map
Mixing outline and solid icon styles within the same section	Pick one style per section and apply consistently
Using emoji instead of proper icon components	Always use tree-shakeable icon components from Lucide, Heroicons, or Phosphor
Hardcoding color values like `text-blue-500` on icons	Use semantic colors like `text-primary` so icons inherit theme changes
Choosing icons by visual appeal rather than semantic meaning	Map the concept first using the semantic mapping reference, then select the icon
Missing `aria-label` on icon-only buttons	Add `aria-label="Description"` to buttons containing only icons
Using old Heroicons import paths without size prefix	Use `@heroicons/react/24/outline` with the size prefix

Delegation

Audit existing icon usage for consistency and tree-shaking issues: Use Explore agent to scan imports and identify mixed styles or wildcard imports
Migrate icons from Font Awesome or Material to modern libraries: Use Task agent with the migration guide reference
Plan icon system architecture for a design system: Use Plan agent to select library, define sizing conventions, and establish semantic mappings

References

semantic-mapping.md -- Full concept-to-icon tables by category (quality, price, location, trade-specific, navigation, status)
icon-templates.md -- React/HTML patterns with Tailwind (feature cards, buttons, inputs, navigation, status badges)
library-comparison.md -- Lucide vs Heroicons vs Phosphor (features, bundle size, import patterns)
migration-guide.md -- Font Awesome, Material Icons, Feather, and emoji to modern equivalents
accessibility.md -- Decorative vs meaningful icons, aria attributes, screen reader patterns

icon-design