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<string, LucideIcon> = { Home, Users, Settings } const Icon = ICON_MAP[iconName]

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