Icon System

The Ellemment Stack implements a performant SVG sprite-based icon system. This approach provides optimal performance by combining all icons into a single sprite file, reducing HTTP requests and improving load times.

Icon Management

Directory Structure

Raw SVG files are stored in:

./other/svg-icons/

Build Process

The build process:

1. Compiles SVGs into a sprite file (icon.svg)
2. Generates a manifest file (icons.json)
3. Provides TypeScript icon name definitions

Adding Icons

Using Sly CLI

The easiest way to add icons is using Sly:

# Add specific icons
npx sly add @radix-ui/icons trash pencil-1 avatar
,[object Object],
npx sly add @radix-ui/icons

Manual Addition

1. Download SVG files
2. Place in ./other/svg-icons/
3. Run build command:

   npm run build:icons

Icon Sources

Default icons come from Radix UI Icons. You can:

• Download additional Radix icons
• Add custom SVG icons
• Use icons from other sources

File Naming Convention

Use kebab-case for icon filenames:

✅ user-profile.svg
✅ arrow-right.svg
❌ UserProfile.svg
❌ arrowRight.svg

This ensures consistent behavior across different operating systems.

Icon Properties

Automatic Processing

The build process automatically:

• Removes width and height attributes
• Ensures proper scaling
• Optimizes SVG code

Default Behavior

Icons will:

• Scale relative to text (1em)
• Match surrounding font size
• Maintain aspect ratio
• Support custom sizing

Usage

Basic Implementation

import { Icon } from '~/components'

function Component() {
  return <Icon name="user-profile" />
}

Custom Sizing

<Icon name="user-profile" size={24} />

With Text

<div className="flex items-center">
  <Icon name="user-profile" />
  <span className="ml-2">User Profile</span>
</div>

Best Practices

1. Performance

   • Keep sprites minimal
   • Remove unused icons
   • Optimize SVG files

2. Accessibility

   • Use descriptive names
   • Add aria labels
   • Maintain contrast

3. Maintenance

   • Regular sprite updates
   • Clean old icons
   • Version control sprites

Build Configuration

The build process is configured in:

./other/build-icons.ts

Key features:

• Sprite generation
• Icon optimization
• TypeScript integration
• Manifest generation

Technical Details

SVG Sprite Benefits

• Single HTTP request
• Browser caching
• Reduced overhead
• Consistent styling

Implementation Notes

• Icons scale with text size
• Support custom dimensions
• Maintain aspect ratios
• Cross-browser compatible

For more information about performance considerations, see the performance documentation.