icon-design

name	icon-design
description	Select semantically appropriate icons for websites using Lucide, Heroicons, or Phosphor. Covers concept-to-icon mapping, React/HTML templates, and tree-shaking patterns. Use when: building feature sections, service grids, contact info, navigation, or any UI needing icons. Prevents emoji usage, ensures consistency.

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

1. Never mix styles - Use all outline OR all solid in a section
2. Never use emoji - Use proper icon components (tree-shakeable)
3. Use currentColor - Icons inherit text color via stroke="currentColor"
4. 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<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

Selection Process

1. Identify the concept - What does the label/title communicate?
2. Check semantic mapping - See references/semantic-mapping.md
3. Choose library - Lucide (default), Heroicons (Tailwind), Phosphor (weights)
4. Apply template - See references/icon-templates.md
5. 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