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)

Library Selection

Default recommendation: Lucide (1,400+ icons, excellent React integration)

See references/library-comparison.md for detailed comparison.

Icon Style Rules

Sizing

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