Icon Design
Select the right icon for the job. Maps concepts to icons, provides templates, prevents common mistakes.
Quick Reference (Top 20 Concepts) 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/Favourite 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,400+ icons, excellent React integration)
See references/library-comparison.md for detailed comparison.
Icon Style Rules Sizing Context Tailwind Class Pixels Inline with text w-4 h-4 or w-5 h-5 16-20px Feature cards w-8 h-8 32px Hero sections w-10 h-10 or w-12 h-12 40-48px Large decorative w-16 h-16 64px Consistency Rules Never mix styles - Use all outline OR all solid in a section Never use emoji - Use proper icon components (tree-shakeable) Use currentColor - Icons inherit text color via stroke="currentColor" Semantic colours - Use text-primary, not text-blue-500 Tree-Shaking (Critical)
Dynamic icon selection breaks tree-shaking. Use explicit maps:
// BAD - all icons bundled import * as Icons from 'lucide-react' const Icon = Icons[iconName] // Tree-shaken away!
// GOOD - explicit map
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record
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 in section Decision Tree
When unsure which icon:
Is it about recognition/awards? → Trophy, Star, Award Is it about money/price? → Tag, DollarSign, CreditCard Is it about location? → MapPin, Globe, Map Is it about people/team? → Users, UserGroup, User Is it about communication? → MessageCircle, Phone, Mail Is it about safety/trust? → Shield, Lock, ShieldCheck Is it about speed/time? → Zap, Clock, Timer Is it trade-specific? → Check semantic-mapping.md Still unsure? → CheckCircle (generic positive) or Sparkles (generic feature)
Resources references/semantic-mapping.md - Full concept→icon tables by category references/icon-templates.md - React/HTML patterns with Tailwind references/library-comparison.md - Lucide vs Heroicons vs Phosphor references/migration-guide.md - FA/Material → modern equivalents rules/icon-design.md - Correction rules for projects