Skip to content

Iconography System.md

Latest commit

 

History

History
475 lines (382 loc) · 11.8 KB

Iconography System.md

File metadata and controls

475 lines (382 loc) · 11.8 KB
Raw
tags
frontend
systems
iconography
icons
type system-doc

Iconography System

Comprehensive guide to icon design principles, implementation, and best practices for UI icon systems.

Icon Fundamentals

What Makes a Good Icon

  • Clear: Instantly recognizable and understandable
  • Consistent: Follows the same style across the set
  • Scalable: Works at multiple sizes without losing detail
  • Accessible: Meets contrast and size requirements
  • Purposeful: Each icon has a clear, unique meaning

Icon Types

1. Glyph Icons

Simple, symbolic representations using basic shapes.

Best For: Navigation, actions, and status indicators.

Example:

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
  <path d="M3 12h18M3 6h18M3 18h18"/>
</svg>

2. Illustrative Icons

More detailed, storytelling icons with multiple elements.

Best For: Empty states, onboarding, and feature highlights.

Example:

<svg width="64" height="64" viewBox="0 0 64 64" fill="none">
  <circle cx="32" cy="32" r="28" fill="#e0e0e0"/>
  <path d="M20 32 L28 40 L44 24" stroke="#4CAF50" stroke-width="4" stroke-linecap="round"/>
</svg>

3. Line Icons

Stroke-based icons with uniform line weights.

Best For: Clean, modern interfaces and minimal designs.

Example:

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
  <circle cx="12" cy="12" r="10"/>
  <path d="M12 6v6l4 2"/>
</svg>

4. Filled Icons

Solid shapes without strokes.

Best For: High-contrast interfaces and emphasis.

Example:

<svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
  <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>
</svg>

Icon Design Principles

1. Consistent Grid System

Use a consistent grid for all icons to ensure alignment and harmony.

:root {
  --icon-size-sm: 16px;
  --icon-size-md: 24px;
  --icon-size-lg: 32px;
  --icon-size-xl: 48px;
}

.icon {
  width: var(--icon-size-md);
  height: var(--icon-size-md);
}

2. Uniform Stroke Width

Maintain consistent stroke weights across the icon set.

.icon--thin { stroke-width: 1px; }
.icon--regular { stroke-width: 1.5px; }
.icon--medium { stroke-width: 2px; }
.icon--bold { stroke-width: 2.5px; }

3. Optical Alignment

Adjust icon positioning to account for optical illusions.

<!-- Visually centered circle -->
<svg viewBox="0 0 24 24">
  <circle cx="12" cy="12" r="10"/>
</svg>

<!-- Optically centered square -->
<svg viewBox="0 0 24 24">
  <rect x="4" y="4" width="16" height="16"/>
</svg>

4. Consistent Corner Radius

Use the same border radius for rounded elements.

:root {
  --icon-radius-sm: 2px;
  --icon-radius-md: 4px;
  --icon-radius-lg: 6px;
}

Icon Implementation

SVG Sprites

Efficient method for using multiple icons with a single HTTP request.

<!-- SVG Sprite Definition -->
<svg style="display: none;">
  <symbol id="icon-home" viewBox="0 0 24 24">
    <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
  </symbol>
  <symbol id="icon-user" viewBox="0 0 24 24">
    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
  </symbol>
</svg>

<!-- Usage -->
<svg class="icon">
  <use href="#icon-home"/>
</svg>

Icon Fonts

Traditional method using font files for icons.

@font-face {
  font-family: 'IconFont';
  src: url('iconfont.woff2') format('woff2');
}

.icon {
  font-family: 'IconFont';
  font-size: 24px;
  speak: none;
}

.icon-home::before { content: '\e900'; }
.icon-user::before { content: '\e901'; }

Inline SVGs

Direct SVG embedding for maximum control and styling.

<button class="btn">
  <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
    <path d="M3 12h18M3 6h18M3 18h18"/>
  </svg>
  Menu
</button>

Icon Components

React components for icon systems.

// Icon Component
const Icon = ({ name, size = 24, className = '' }) => {
  const icons = {
    home: <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>,
    user: <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
  };

  return (
    <svg 
      width={size} 
      height={size} 
      viewBox="0 0 24 24" 
      fill="currentColor"
      className={className}
    >
      {icons[name]}
    </svg>
  );
};

// Usage
<Icon name="home" size={32} className="nav-icon" />

Icon Styling

Size Variants

.icon--xs { width: 12px; height: 12px; }
.icon--sm { width: 16px; height: 16px; }
.icon--md { width: 24px; height: 24px; }
.icon--lg { width: 32px; height: 32px; }
.icon--xl { width: 48px; height: 48px; }
.icon--2xl { width: 64px; height: 64px; }

Color Variants

.icon--primary { color: var(--color-primary); }
.icon--secondary { color: var(--color-secondary); }
.icon--success { color: var(--color-success); }
.icon--warning { color: var(--color-warning); }
.icon--error { color: var(--color-error); }
.icon--inherit { color: inherit; }

Interactive States

.icon--interactive {
  cursor: pointer;
  transition: color 0.2s ease, transform 0.2s ease;
}

.icon--interactive:hover {
  color: var(--color-primary);
  transform: scale(1.1);
}

.icon--interactive:active {
  transform: scale(0.95);
}

Animation Variants

/* Spin Animation */
.icon--spin {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

/* Pulse Animation */
.icon--pulse {
  animation: pulse 2s ease-in-out infinite;
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}

/* Bounce Animation */
.icon--bounce {
  animation: bounce 0.5s ease;
}

@keyframes bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-25%); }
}

Icon Accessibility

ARIA Labels

Always provide accessible labels for icons.

<!-- With text -->
<button>
  <svg class="icon" aria-hidden="true">
    <use href="#icon-home"/>
  </svg>
  Home
</button>

<!-- Standalone icon -->
<button aria-label="Home">
  <svg class="icon">
    <use href="#icon-home"/>
  </svg>
</button>

<!-- Decorative icon -->
<div class="icon-container">
  <svg class="icon" aria-hidden="true">
    <use href="#icon-star"/>
  </svg>
</div>

Focus Indicators

Ensure keyboard users can see focus on icon buttons.

.icon-button {
  background: none;
  border: none;
  padding: 8px;
  cursor: pointer;
}

.icon-button:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
  border-radius: 4px;
}

Minimum Size Requirements

Ensure icons meet minimum touch target sizes.

.icon-button {
  min-width: 44px;
  min-height: 44px;
  display: flex;
  align-items: center;
  justify-content: center;
}

Icon Categories

Navigation Icons

<!-- Home -->
<svg viewBox="0 0 24 24"><path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/></svg>

<!-- Menu -->
<svg viewBox="0 0 24 24"><path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z"/></svg>

<!-- Search -->
<svg viewBox="0 0 24 24"><path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/></svg>

Action Icons

<!-- Add -->
<svg viewBox="0 0 24 24"><path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/></svg>

<!-- Edit -->
<svg viewBox="0 0 24 24"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"/></svg>

<!-- Delete -->
<svg viewBox="0 0 24 24"><path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z"/></svg>

Status Icons

<!-- Success -->
<svg viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/></svg>

<!-- Warning -->
<svg viewBox="0 0 24 24"><path d="M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z"/></svg>

<!-- Error -->
<svg viewBox="0 0 24 24"><path d="M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2zm5 13.59L15.59 17 12 13.41 8.41 17 7 15.59 10.59 12 7 8.41 8.41 7 12 10.59 15.59 7 17 8.41 13.41 12 17 15.59z"/></svg>

Communication Icons

<!-- Email -->
<svg viewBox="0 0 24 24"><path d="M20 4H4c-1.1 0-1.99.9-1.99 2L2 18c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V6c0-1.1-.9-2-2-2zm0 4l-8 5-8-5V6l8 5 8-5v2z"/></svg>

<!-- Phone -->
<svg viewBox="0 0 24 24"><path d="M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1-9.39 0-17-7.61-17-17 0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.25.2 2.45.57 3.57.11.35.03.74-.25 1.02l-2.2 2.2z"/></svg>

<!-- Chat -->
<svg viewBox="0 0 24 24"><path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2z"/></svg>

Icon Best Practices

Do's

  • Keep it simple: Focus on essential elements
  • Maintain consistency: Use the same style across all icons
  • Test at scale: Ensure icons work at various sizes
  • Consider accessibility: Provide labels and sufficient contrast
  • Use semantic names: Name icons by their function, not appearance
  • Optimize file size: Remove unnecessary code from SVGs
  • Document usage: Create guidelines for icon application

Don'ts

  • Avoid over-detailing: Too much detail becomes unclear at small sizes
  • Don't mix styles: Keep all icons in the same visual style
  • Avoid meaningless icons: Each icon should have clear purpose
  • Don't ignore cultural differences: Some symbols have different meanings
  • Avoid relying on color alone: Use shape and form for recognition
  • Don't forget hover states: Provide feedback for interactive icons
  • Avoid inconsistent stroke weights: Maintain uniform line thickness

Icon Resources

Icon Libraries

  • Heroicons: Clean, modern SVG icons
  • Material Icons: Google's material design icons
  • Feather Icons: Beautiful, consistent icon set
  • Ionicons: Premium icon library for web and mobile
  • Lucide: Friendly & free icon library

Icon Tools

  • Figma: Design and export icons
  • Sketch: Icon design and organization
  • Illustrator: Professional icon creation
  • IconJar: Icon management for designers
  • Nucleo: Icon library and management

Icon Accessibility Tools

  • WAVE: Web accessibility evaluation tool
  • AXE: Browser extension for accessibility testing
  • Lighthouse: Chrome's built-in accessibility audit
  • Colour Contrast Analyser: Check color contrast ratios

Icon System Documentation Template

# Iconography System

## Icon Styles
- Primary style: [Line/Filled/Glyph]
- Stroke width: [Xpx]
- Corner radius: [Xpx]
- Grid size: [24x24]

## Size Scale
- XS: 12px - [Usage]
- SM: 16px - [Usage]
- MD: 24px - [Usage]
- LG: 32px - [Usage]
- XL: 48px - [Usage]

## Color Application
- Primary: [Color] - [Usage]
- Secondary: [Color] - [Usage]
- Success: [Color] - [Usage]
- Warning: [Color] - [Usage]
- Error: [Color] - [Usage]

## Usage Guidelines
- When to use icons: [Guidelines]
- When to use text instead: [Guidelines]
- Icon + text combinations: [Guidelines]
- Spacing requirements: [Guidelines]

## Accessibility
- ARIA labeling: [Requirements]
- Minimum touch targets: [Size]
- Focus indicators: [Requirements]
- Color contrast: [Requirements]

## Implementation
- File format: [SVG/PNG/Font]
- Optimization: [Techniques]
- Fallbacks: [Strategies]
- Performance: [Considerations]

This comprehensive iconography system guide provides everything needed to create, implement, and maintain a professional icon system for any UI design project.