Icons in Design Systems

Icons are foundational elements of design systems. When properly integrated, they ensure visual consistency across products, streamline designer and developer workflows, and scale with your organization's needs.

Icons as Design System Components

In a design system, icons aren't just graphics—they're components with defined:

• Properties - Size, color, variant (outlined/filled)
• Behavior - How they respond to states and themes
• Usage guidelines - When and where to use each icon
• Accessibility requirements - Labels, contrast, alternatives
• Implementation specs - How developers integrate them

Defining Icon Properties

Standardize icon properties across the system:

Size Scale

// Example size tokens
icon-size-xs: 12px
icon-size-sm: 16px
icon-size-md: 20px
icon-size-lg: 24px
icon-size-xl: 32px
icon-size-2xl: 48px

Limit sizes to your scale. Don't allow arbitrary sizing—it creates inconsistency.

Color Tokens

// Semantic icon colors
icon-color-default: gray-700
icon-color-muted: gray-500
icon-color-primary: brand-600
icon-color-success: green-600
icon-color-warning: yellow-600
icon-color-error: red-600
icon-color-on-dark: white

Variants

• Style variants - outlined, filled, duotone
• Weight variants - light, regular, bold (if applicable)
• State variants - default, active, disabled

Icon Component API

Design your icon component API for flexibility and constraints:

// React example
<Icon 
  name="home"
  size="lg"           // Constrained to size scale
  color="primary"     // Uses color tokens
  variant="outlined"  // Style variant
  label="Home page"   // Accessibility
/>

The API should expose only properties that align with your design system.

Figma Component Setup

In Figma, create icons as components with variants:

• Main component frame at your base size (e.g., 24×24)
• Variants for style (outlined/filled) and state
• Named consistently with your code naming
• Published to team library

Use Figma's variant properties for easy swapping in designs.

Code Package Structure

Organize icons for developer consumption:

@mycompany/icons
├── src/
│   ├── icons/           # Individual SVG components
│   │   ├── Home.tsx
│   │   ├── Settings.tsx
│   │   └── ...
│   ├── Icon.tsx         # Base icon component
│   ├── index.ts         # Exports
│   └── types.ts         # TypeScript definitions
├── dist/                # Built output
├── CHANGELOG.md
└── package.json

Synchronizing Design and Code

Keep design and development in sync:

• Single source of truth - Define icons in one place
• Automated export - Scripts to extract from design tools
• CI/CD pipeline - Automatically publish updates
• Version matching - Design and code versions align

Tools like Figma API, Storybook, and dedicated design system platforms help bridge the gap.

Documentation Requirements

Document icons thoroughly in your design system docs:

• Visual browser - Searchable grid of all icons
• Usage guidelines - When to use each icon
• Code examples - Copy-paste implementation
• Accessibility notes - Labeling requirements
• Design specs - Sizing, spacing, alignment
• Do's and don'ts - Visual examples

Request and Addition Process

Define how new icons enter the system:

1. Request - Team submits icon need with use case
2. Review - Check if existing icon suffices
3. Design - Create following guidelines
4. Approval - Style review and naming consensus
5. Implementation - Add to Figma and code packages
6. Documentation - Update docs with new icon
7. Release - Publish new version

Deprecation Strategy

Handle icon removal carefully:

• Deprecation notice - Warn before removing
• Migration path - Suggest replacement icons
• Grace period - Allow time for teams to update
• Breaking version - Remove in major version only

// Deprecated icon warning
/**
 * @deprecated Use 'ArrowRight' instead. Will be removed in v3.0.0
 */
export const RightArrow = ArrowRight;

Theming Support

Icons should adapt to design system themes:

// Theme-aware icon colors
const Icon = ({ name, color = 'default' }) => {
  const theme = useTheme();
  const iconColor = theme.colors.icon[color];
  return <SvgIcon name={name} fill={iconColor} />;
};

// Automatic dark mode support
:root {
  --icon-default: #333;
}
[data-theme="dark"] {
  --icon-default: #fff;
}

Quality Metrics

Track icon system health:

• Adoption rate - Percentage of products using system icons
• Coverage - How often teams need icons not in the system
• Consistency - Audit for non-system icon usage
• Accessibility compliance - Labeled vs unlabeled icons

Scaling the System

As organizations grow, icon systems need to scale:

• Multiple packages for different platforms (web, iOS, Android)
• Sub-libraries for product-specific icons
• Contribution guidelines for decentralized teams
• Automated quality checks and linting