Icon Design

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

Library Selection

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

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 within each section

Icon Style Rules

Common Mistakes

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 Accessibility

Proper handling of icons for screen readers and assistive technologies.

Decorative vs Meaningful Icons

Icons fall into two categories with different accessibility requirements.

Decorative Icons (Next to Text)

Icons alongside visible text are decorative -- the text already provides meaning. Hide them from screen readers:

<span className="flex items-center gap-2">
  <Phone aria-hidden="true" className="w-4 h-4" />
  <span>Call us</span>
</span>

Meaningful Icons (Standalone)

Icons conveying information without accompanying text need an accessible label:

<CheckCircle aria-label="Completed" className="w-5 h-5 text-green-600" />

Icon-Only Buttons

Buttons containing only an icon need aria-label on the button element:

<button aria-label="Open menu" className="p-2 rounded-lg hover:bg-muted">
  <Menu className="w-6 h-6" />
</button>

<button aria-label="Close dialog" className="p-2 rounded-lg hover:bg-muted">
  <X className="w-5 h-5" />
</button>

<button aria-label="Search" className="p-2 rounded-lg hover:bg-muted">
  <Search className="w-5 h-5" />
</button>

Icon-Only Links

Links containing only an icon follow the same pattern:

<a href="/settings" aria-label="Settings">
  <Settings className="w-5 h-5" />
</a>

Tooltip Wrapping for Lucide

Lucide icons do not accept HTML attributes like title directly. Wrap in a container:

<span title="Award Winner">
  <Trophy aria-hidden="true" className="w-5 h-5" />
</span>

Status Icons with Screen Reader Text

For status indicators, provide screen-reader-only text:

<span className="flex items-center gap-1.5">
  <CheckCircle aria-hidden="true" className="w-4 h-4 text-green-600" />
  <span>Active</span>
</span>

When there is no visible text, use visually hidden text:

<span className="flex items-center">
  <AlertTriangle aria-hidden="true" className="w-4 h-4 text-yellow-600" />
  <span className="sr-only">Warning status</span>
</span>

Color and Contrast

Icons must meet WCAG contrast requirements:

• Icons conveying information need 3:1 contrast ratio against background
• Decorative icons have no contrast requirement
• Do not rely on color alone to convey meaning -- pair with text or shape differences

<span className="flex items-center gap-1.5">
  <XCircle aria-hidden="true" className="w-4 h-4 text-destructive" />
  <span className="text-destructive">Error: Upload failed</span>
</span>

Focus Indicators

Icon-only interactive elements must have visible focus indicators:

<button
  aria-label="Delete item"
  className="p-2 rounded-lg hover:bg-muted focus-visible:outline-2 focus-visible:outline-primary"
>
  <Trash2 className="w-5 h-5" />
</button>

Common Mistakes

Icon Templates

Ready-to-use patterns for common icon layouts using Tailwind v4 semantic colors.

Feature Card Icon (Rounded Square)

import { Trophy } from 'lucide-react';

<div className="w-14 h-14 rounded-xl bg-primary/10 flex items-center justify-center">
  <Trophy className="w-8 h-8 text-primary" />
</div>;

Heroicons variant:

import { TrophyIcon } from '@heroicons/react/24/outline';

<div className="w-14 h-14 rounded-xl bg-primary/10 flex items-center justify-center">
  <TrophyIcon className="w-8 h-8 text-primary" />
</div>;

Feature Card Icon (Circle)

import { Shield } from 'lucide-react';

<div className="w-12 h-12 rounded-full bg-primary/10 flex items-center justify-center">
  <Shield className="w-6 h-6 text-primary" />
</div>;

Inline Icon (Contact Info)

import { Phone, Mail, MapPin } from 'lucide-react'

<span className="inline-flex items-center gap-2 text-muted-foreground">
  <Phone aria-hidden="true" className="w-4 h-4" />
  <span>1300 123 456</span>
</span>

<span className="inline-flex items-center gap-2 text-muted-foreground">
  <Mail aria-hidden="true" className="w-4 h-4" />
  <span>hello@example.com</span>
</span>

<span className="inline-flex items-center gap-2 text-muted-foreground">
  <MapPin aria-hidden="true" className="w-4 h-4" />
  <span>Sydney, Australia</span>
</span>

List Item with Icon

import { Check } from 'lucide-react';

<ul className="space-y-3">
  <li className="flex items-start gap-3">
    <Check
      aria-hidden="true"
      className="w-5 h-5 text-primary flex-shrink-0 mt-0.5"
    />
    <span>First benefit or feature</span>
  </li>
  <li className="flex items-start gap-3">
    <Check
      aria-hidden="true"
      className="w-5 h-5 text-primary flex-shrink-0 mt-0.5"
    />
    <span>Second benefit or feature</span>
  </li>
</ul>;

Button with Icon

import { ArrowRight } from 'lucide-react'

<button className="inline-flex items-center gap-2 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90">
  <span>Get Started</span>
  <ArrowRight aria-hidden="true" className="w-4 h-4" />
</button>

<button className="inline-flex items-center gap-2 px-4 py-2 border border-border rounded-lg hover:bg-muted">
  <span>Learn More</span>
  <ArrowRight aria-hidden="true" className="w-4 h-4" />
</button>

Icon-Only Button

import { Menu, X, Search } from 'lucide-react'

<button
  className="p-2 rounded-lg hover:bg-muted transition-colors"
  aria-label="Open menu"
>
  <Menu className="w-6 h-6" />
</button>

<button
  className="p-2 rounded-lg hover:bg-muted transition-colors"
  aria-label="Close"
>
  <X className="w-5 h-5" />
</button>

<button
  className="p-2 rounded-lg hover:bg-muted transition-colors"
  aria-label="Search"
>
  <Search className="w-5 h-5" />
</button>

Feature Grid Card

import { Shield, Zap, Users, Trophy } from 'lucide-react'

const features = [
  { icon: Shield, title: 'Secure', description: 'Enterprise-grade security' },
  { icon: Zap, title: 'Fast', description: 'Lightning quick response' },
  { icon: Users, title: 'Support', description: '24/7 expert help' },
  { icon: Trophy, title: 'Award-Winning', description: 'Industry recognized' },
]

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
  {features.map(({ icon: Icon, title, description }) => (
    <div key={title} className="p-6 rounded-xl bg-card border border-border">
      <div className="w-12 h-12 rounded-lg bg-primary/10 flex items-center justify-center mb-4">
        <Icon aria-hidden="true" className="w-6 h-6 text-primary" />
      </div>
      <h3 className="font-semibold text-card-foreground mb-2">{title}</h3>
      <p className="text-sm text-muted-foreground">{description}</p>
    </div>
  ))}
</div>

Status Badge with Icon

import { CheckCircle, XCircle, AlertTriangle, Clock } from 'lucide-react'

<span className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-green-500/10 text-green-600 text-sm">
  <CheckCircle aria-hidden="true" className="w-4 h-4" />
  <span>Active</span>
</span>

<span className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-destructive/10 text-destructive text-sm">
  <XCircle aria-hidden="true" className="w-4 h-4" />
  <span>Failed</span>
</span>

<span className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-yellow-500/10 text-yellow-600 text-sm">
  <AlertTriangle aria-hidden="true" className="w-4 h-4" />
  <span>Warning</span>
</span>

<span className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-muted text-muted-foreground text-sm">
  <Clock aria-hidden="true" className="w-4 h-4" />
  <span>Pending</span>
</span>

Navigation Item

import { Home, Users, Settings, type LucideIcon } from 'lucide-react';

interface NavItemProps {
  icon: LucideIcon;
  label: string;
  href: string;
  active?: boolean;
}

function NavItem({ icon: Icon, label, href, active }: NavItemProps) {
  return (
    <a
      href={href}
      className={cn(
        'flex items-center gap-3 px-3 py-2 rounded-lg transition-colors',
        active
          ? 'bg-primary/10 text-primary'
          : 'text-muted-foreground hover:bg-muted hover:text-foreground',
      )}
    >
      <Icon aria-hidden="true" className="w-5 h-5" />
      <span>{label}</span>
    </a>
  );
}

Input with Icon

import { Search, Mail } from 'lucide-react'

<div className="relative">
  <Search aria-hidden="true" className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-muted-foreground" />
  <input
    type="text"
    placeholder="Search..."
    className="w-full pl-10 pr-4 py-2 rounded-lg border border-border bg-background focus:outline-none focus:ring-2 focus:ring-primary"
  />
</div>

<div className="relative">
  <Mail aria-hidden="true" className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-muted-foreground" />
  <input
    type="email"
    placeholder="Enter your email"
    className="w-full pl-10 pr-4 py-2 rounded-lg border border-border bg-background focus:outline-none focus:ring-2 focus:ring-primary"
  />
</div>

Dynamic Icon Map (Tree-Shaking Safe)

import { Home, Users, Settings, type LucideIcon } from 'lucide-react';

const ICON_MAP: Record<string, LucideIcon> = {
  home: Home,
  users: Users,
  settings: Settings,
};

function DynamicIcon({
  name,
  ...props
}: { name: string } & React.SVGProps<SVGSVGElement>) {
  const Icon = ICON_MAP[name];
  if (!Icon) return null;
  return <Icon {...props} />;
}

Color Reference

All templates use Tailwind v4 semantic tokens:

Never use raw colors like text-blue-500 -- always use semantic tokens.

Library Comparison

Detailed comparison of Lucide, Heroicons, and Phosphor icon libraries.

Overview

Lucide (Default Recommendation)

Best for React/Vue/Svelte projects, general-purpose applications, and teams familiar with Feather Icons.

npm install lucide-react

import { Home, Settings, User } from 'lucide-react'

<Home className="w-6 h-6" />
<Settings className="w-6 h-6" strokeWidth={1.5} />

Strengths: Large library with frequent updates, excellent React integration, PascalCase component names, customizable stroke width, dynamic loading via lucide-react/dynamic.

Dynamic Icon Loading

For icons loaded by name (from database, CMS, etc.), use the DynamicIcon component. Not recommended for static usage due to build performance impacts:

import { DynamicIcon } from 'lucide-react/dynamic';

<DynamicIcon name="camera" color="red" size={48} />;

Custom Icons from @lucide/lab

Use the generic Icon component to render experimental icons from @lucide/lab:

import { Icon } from 'lucide-react';
import { coconut } from '@lucide/lab';

<Icon iconNode={coconut} size={24} />;

Limitations: No weight variations (outline only), some inconsistency from community contributions.

Heroicons

Best for Tailwind CSS projects, minimal aesthetic, and projects using Tailwind UI components.

npm install @heroicons/react

import { HomeIcon } from '@heroicons/react/24/outline';
import { HomeIcon } from '@heroicons/react/24/solid';
import { HomeIcon } from '@heroicons/react/20/solid';
import { HomeIcon } from '@heroicons/react/16/solid';

<HomeIcon className="w-6 h-6" />;

Strengths: Official Tailwind integration, consistent design, four styles per icon (outline, solid, mini, micro), three sizes (16, 20, 24px).

Limitations: Smaller library (316 icons), verbose import paths.

Phosphor

Best for weight variations (thin, light, regular, bold, fill, duotone), large icon needs, and design-heavy projects.

npm install @phosphor-icons/react

import { House, Gear, User } from '@phosphor-icons/react'

<House size={24} />
<House size={24} weight="thin" />
<House size={24} weight="bold" />
<House size={24} weight="fill" />
<House size={24} weight="duotone" />

Strengths: Largest library (7,000+ icons), 6 weight variations per icon, consistent design language, unique duotone variant.

Limitations: Larger bundle if using multiple weights, less React-ecosystem adoption.

Tree-Shaking Patterns

All three libraries support tree-shaking with specific imports:

import { Home, User, Settings } from 'lucide-react';
import { HomeIcon, UserIcon } from '@heroicons/react/24/outline';
import { House, User, Gear } from '@phosphor-icons/react';

Never use wildcard imports -- they bundle all icons:

import * as Icons from 'lucide-react';
const Icon = Icons[iconName];

Use an explicit map instead:

import { Home, User, Settings, type LucideIcon } from 'lucide-react';

const ICON_MAP: Record<string, LucideIcon> = {
  home: Home,
  user: User,
  settings: Settings,
};

const Icon = ICON_MAP[iconName];

Bundle Size (20 Icons)

Recommendation Matrix

Migration Guide

Migrate from legacy icon libraries to modern alternatives.

Font Awesome to Lucide/Phosphor

Font Awesome Style Mapping

Material Icons to Lucide/Phosphor

Feather Icons to Lucide

Lucide is a direct fork of Feather Icons with the same naming:

import { Home, User, Settings } from 'feather-icons-react';

import { Home, User, Settings } from 'lucide-react';

Migration is a package swap -- icon names are identical in PascalCase.

Emoji to Icon Components

Never use emoji for UI icons. Replace with proper icon components:

Why icons over emoji: consistent styling across platforms, accessible to screen readers, themeable with CSS, tree-shakeable for performance.

Semantic Icon Mapping

Maps concepts to icons across Lucide, Heroicons, and Phosphor libraries. Find the category matching your content, look up the concept, and choose from recommended icons.

Quality and Recognition

Price and Value

Location and Local

Expertise and Professional

Support and Service

Security and Trust

Speed and Efficiency

Trade-Specific

Contact Information

Social media icons (Facebook, Instagram, LinkedIn, Twitter/X, YouTube) should use official brand SVGs or react-icons/fa, not generic icon libraries.

Navigation and Actions

Status and Feedback

Decision Tree

When the concept does not match the tables above:

1. Achievement/quality? -- Trophy, Star, Award, BadgeCheck 2. Money/cost? -- Tag, DollarSign, Wallet, Percent 3. Place/location? -- MapPin, Globe, Map, Navigation 4. People/users? -- User, Users, UserGroup 5. Communication? -- MessageCircle, Phone, Mail, Chat 6. Safety/security? -- Shield, Lock, ShieldCheck, Key 7. Time/speed? -- Zap, Clock, Timer, Calendar 8. Industry-specific? -- Check the Trade-Specific table 9. Generic positive? -- CheckCircle, ThumbsUp, Sparkles 10. Generic feature? -- Sparkles, Star, Zap