Icons

---

name: Icons description: Implement accessible icons with proper sizing, color inheritance, and performance. metadata: {"clawdbot":{"emoji":"🔣","requires":{},"os":["linux","darwin","win32"]}}

SVG vs Icon Fonts

SVG is the modern standard:

• Better accessibility (native ARIA support)
• No flash of invisible/wrong icon (FOIT)
• Multicolor support
• Smaller bundles with tree-shaking

Only consider icon fonts for legacy IE11 support.

Accessibility Patterns

Decorative icons (next to visible text):

<button>
  <svg aria-hidden="true" focusable="false">...</svg>
  Save
</button>

Informative icons (standalone, no label):

<button aria-label="Save document">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

<!-- Or with visually hidden text -->
<button>
  <svg aria-hidden="true">...</svg>
  <span class="sr-only">Save document</span>
</button>

SVG with accessible name:

<svg role="img" aria-labelledby="icon-title">
  <title id="icon-title">Warning: system error</title>
  <!-- paths -->
</svg>

Key rules:

• aria-hidden="true" on SVGs that duplicate visible text
• focusable="false" prevents unwanted tab stops in IE/Edge
• <title> must be first child inside <svg> for screen reader support
• IDs must be unique if multiple SVGs are inline

Color Inheritance

<svg fill="currentColor">
  <path d="..."/>
</svg>

currentColor inherits from CSS color property. The icon changes color with hover states automatically:

.button { color: blue; }
.button:hover { color: red; } /* icon turns red too */

Remove hardcoded fill="#000" from SVGs before using currentColor.

For stroke-based icons, use stroke="currentColor" instead.

Sizing

Standard grid sizes: 16, 20, 24, 32px

Match stroke weight to size:

Touch targets need 44x44px minimum—icon can be smaller if tappable area is larger via padding.

.icon-button {
  width: 24px;
  height: 24px;
  padding: 10px; /* Creates 44x44 touch target */
}

Scaling with Text

.icon {
  width: 1em;
  height: 1em;
}

Icon scales with surrounding text size automatically.

Symbol Sprites

For many repeated icons, reduce DOM nodes with sprites:

<!-- Define once, hidden -->
<svg style="display:none">
  <symbol id="icon-search" viewBox="0 0 24 24">
    <path d="..."/>
  </symbol>
  <symbol id="icon-menu" viewBox="0 0 24 24">
    <path d="..."/>
  </symbol>
</svg>

<!-- Use anywhere -->
<svg aria-hidden="true"><use href="#icon-search"/></svg>

External sprites (<use href="/icons.svg#search"/>) don't work in older Safari without polyfill.

Performance

Benchmark (1000 icons):

• <img> with data URI: 67ms (fastest)
• Inline SVG optimized: 75ms
• Symbol sprite: 99ms
• <img> external: 76ms

Recommendations:

• Tree-shake icon libraries (Lucide, Heroicons support this)
• Don't import entire Font Awesome (1MB+)—use subset or switch to SVG
• Inline critical icons, lazy-load sprite for non-critical

Consistency

• Stick to one icon set—mixing styles looks unprofessional
• Match icon stroke weight to your font weight (regular text = 1.5px stroke)
• Pick one style per context: outlined for inactive, filled for active
• Optical alignment differs from mathematical—circles reach edges, squares don't
• Name icons by appearance, not meaning: stopwatch not speed

Common Mistakes

• Missing aria-hidden on decorative icons—screen readers announce gibberish
• Mixing rounded and sharp icon styles in same interface
• Giant icon libraries for 10 icons—massive bundle bloat
• Icon-only buttons without accessible name—impossible to use with screen readers
• Hardcoded colors preventing theme switching
• Stroke width not scaling with icon size—16px icon with 2px stroke looks heavy